How to Use Wazuh Logtest

Whether you’re creating custom detection rules, troubleshooting log parsing issues, or validating decoder changes, Wazuh Logtest is one of the most valuable tools available to Wazuh administrators.

Instead of waiting for live events to flow through your environment, Logtest allows you to simulate the entire detection pipeline and immediately see how Wazuh processes a log entry.

This dramatically reduces development time while helping you identify problems before they reach production.

You can verify that a decoder extracts the correct fields, confirm that rules trigger as expected, and determine why an event fails to generate an alert. This can be done all without impacting your production environment.

For organizations that rely on Wazuh for threat detection, intrusion monitoring, compliance, and security operations, testing detection logic before deployment minimizes false positives, prevents missed detections, and improves overall detection quality.

Throughout this guide, you’ll learn exactly how Wazuh Logtest works, how to use it effectively, interpret its output, troubleshoot common problems, and build reliable custom detection rules with confidence.

What Is Wazuh Logtest?

Definition of Wazuh Logtest

Wazuh Logtest (wazuh-logtest) is a command-line utility included with the Wazuh Manager that simulates the Wazuh log analysis engine.

It accepts a log entry as input and processes it through the same decoding and rule evaluation pipeline used during normal event processing.

Rather than waiting for a real endpoint or log source to generate an event, Logtest allows administrators to manually submit logs and instantly observe:

How the log is pre-decoded
Which decoder matches the log
Which fields are extracted
Which detection rules are evaluated
Which alert would ultimately be generated

Because it mirrors the production analysis engine, Logtest provides an accurate way to validate new decoders, custom rules, and detection logic before deploying changes.

How Logtest Fits into the Wazuh Detection Pipeline

Every log processed by Wazuh follows a structured analysis pipeline before an alert is generated.

The workflow typically looks like this:

A log is collected by a Wazuh agent or another supported log source.
The log reaches the Wazuh Manager.
Pre-decoding extracts basic metadata, such as timestamps, hostnames, and program names.
The decoder analyzes the log format and extracts structured fields.
Detection rules evaluate those extracted fields.
If rule conditions are satisfied, Wazuh generates an alert.

Wazuh Logtest reproduces steps 3 through 6 without requiring live data.

This makes it possible to test detection logic repeatedly until the desired behavior is achieved.

If you’re developing custom parsers, you may also find Wazuh Decoder Guide helpful for understanding how decoders extract structured data from raw logs.

Similarly, if you’re creating custom detection logic, refer to How to Create Custom Detection Rules in Wazuh (With Examples).

Why Security Analysts Use Logtest

Security teams frequently modify detection rules to support:

Custom applications
Proprietary log formats
Cloud services
Internal security controls
New threat detection techniques

Without testing, even a small syntax mistake can prevent alerts from firing correctly or create excessive false positives.

Logtest enables analysts to verify:

Decoder accuracy
Field extraction
Parent-child rule relationships
Rule inheritance
Severity levels
Alert descriptions
MITRE ATT&CK mappings
Rule chaining behavior

Instead of waiting for production events, analysts receive immediate feedback, allowing them to iterate rapidly during rule development.

Many Wazuh contributors recommend validating every custom decoder and rule using Logtest before production deployment because it closely matches the actual analysis engine and significantly reduces troubleshooting time.

Benefits of Validating Logs Before Deployment

Testing before deployment offers several operational and security advantages.

Faster development

Developers can immediately identify decoder or rule issues without repeatedly generating live events.

Reduced false positives

Rules can be tuned against representative log samples before affecting production alerts.

Improved detection accuracy

You can verify that all expected fields are extracted correctly and that detection rules fire only under the intended conditions.

Lower operational risk

Production rule changes become much safer because they’ve already been validated in a controlled environment.

Easier troubleshooting

Instead of searching through manager logs, Logtest pinpoints exactly where processing succeeds, or fails.

Independent security guidance consistently recommends testing detection content before production deployment as part of detection engineering and continuous validation practices.

Organizations such as the SANS Institute emphasize validating detection logic to reduce operational errors and improve SOC effectiveness.

How Wazuh Logtest Works

Wazuh Logtest follows the same multi-stage analysis pipeline used by the Wazuh Manager when processing incoming events.

Each phase builds upon the previous one until Wazuh determines whether an alert should be generated.

Understanding each stage makes troubleshooting much easier because you can quickly identify where processing stops.

Overview of the Log Analysis Process

Every submitted log passes through four primary stages:

Raw log input
Pre-decoding
Decoder matching
Rule evaluation

Each stage produces output that helps explain how Wazuh interpreted the event.

Rather than simply indicating whether a rule matched, Logtest exposes every intermediate processing step, making it one of the most valuable troubleshooting tools in the Wazuh ecosystem.

Phase 1: Log Pre-Decoding

The first phase performs lightweight parsing of the raw log.

During pre-decoding, Wazuh attempts to identify information such as:

Timestamp
Hostname
Program name
Syslog header
Message body

No security rules are evaluated during this phase.

Instead, Wazuh prepares the event for decoder matching by separating common log components from the message payload.

If a log lacks a recognizable syslog header, pre-decoding may leave several metadata fields empty, which is completely normal for many custom application logs.

Phase 2: Decoder Matching

Once pre-decoding finishes, Wazuh compares the remaining log content against its decoder library.

Each decoder attempts to match:

Log format
Keywords
Regular expressions
JSON structures
XML fields
Custom patterns

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

Source IP
Username
Process name
Event ID
Destination port
File path
Status codes

Those extracted fields become available to subsequent detection rules.

Organizations that work with complex log formats often build layered decoder hierarchies to improve parsing efficiency.

For advanced implementations, see How to Map Complex Log Fields Using Wazuh Parent Child Rules.

Phase 3: Rule Evaluation

After decoding, Wazuh begins evaluating detection rules.

Rules examine:

Decoder names
Extracted fields
Field values
Parent-child relationships
Rule dependencies
Frequency conditions
Correlation logic
Severity levels

Multiple rules may match the same event before Wazuh determines the highest-priority alert.

This layered evaluation model allows administrators to create highly flexible detection logic while avoiding unnecessary rule duplication.

Understanding the Output at Each Phase

One of Logtest’s greatest strengths is its transparency.

Instead of simply reporting whether a rule matched, it displays the intermediate results generated during each processing stage.

Typical output includes:

Phase	What you’ll see
Pre-decoding	Timestamp, hostname, program name, message body
Decoder	Decoder name, extracted fields, parsed values
Rule evaluation	Matching rule IDs, alert level, description, groups, compliance mappings

When troubleshooting, the first place to look is the last successful phase:

If pre-decoding succeeds but no decoder matches, the decoder likely needs adjustment.
If decoding succeeds but no rules trigger, the rule conditions may be too restrictive.
If multiple unexpected rules fire, rule precedence or inheritance may need refinement.

Learning to interpret these stages can dramatically reduce the time required to diagnose parsing or detection issues.

Prerequisites

Before using Wazuh Logtest, ensure your environment is properly configured.

While the utility is simple to use, successful testing depends on having the necessary components already in place.

Installed and Running Wazuh Manager

Because Logtest runs directly on the Wazuh Manager, the manager service must be installed and operational before testing logs.

You can verify that the manager is running before executing Logtest to avoid misleading errors.

If you’re deploying a new environment, review The Complete Wazuh Cluster Architecture Guide or How to Set Up a Multi-Node Wazuh Cluster for deployment guidance.

Administrative Access

Running Logtest typically requires administrative or root privileges on the Wazuh Manager server.

Administrative access is also necessary when:

Editing decoders
Creating custom rules
Restarting Wazuh services
Validating configuration changes
Reviewing manager logs

Using an account with sufficient privileges helps avoid permission-related issues during testing.

Existing Decoders and Rules

Logtest evaluates logs using the decoders and rules currently loaded by the Wazuh Manager.

Before testing, verify that:

Custom decoders are installed
XML syntax is valid
Rule files are loaded successfully
Configuration changes have been applied

If you’re troubleshooting decoder issues, the following resources can help:

Sample Logs Available for Testing

Meaningful testing requires representative log samples.

Ideally, collect logs directly from:

Production systems (after sanitizing sensitive data)
Development environments
Test servers
Security appliances
Cloud services
Custom applications

Testing with realistic log samples produces far more reliable results than using artificially simplified examples because it exposes formatting inconsistencies that frequently occur in real environments.

Understanding Wazuh Rule IDs and Decoder Hierarchy

Before writing or troubleshooting detection content, it’s helpful to understand how Wazuh organizes its rules.

Each rule is assigned a unique rule ID and may inherit logic from parent rules or depend on a specific decoder.

Understanding these relationships helps explain why:

Certain rules never trigger
Multiple rules match simultaneously
Child rules inherit parent conditions
Decoder selection affects downstream rule evaluation

A solid understanding of decoder hierarchy and rule inheritance makes interpreting Logtest output significantly easier, particularly in large environments with extensive custom detection content.

How to Run Wazuh Logtest

Once your Wazuh Manager is running and your decoders and rules are loaded, you can begin testing logs with wazuh-logtest.

The utility is interactive, making it easy to paste log entries and immediately view how Wazuh processes them through each stage of the detection pipeline.

Using Logtest during rule development significantly shortens troubleshooting time because you receive instant feedback instead of waiting for live events to be ingested.

Launching Logtest

The wazuh-logtest utility is installed alongside the Wazuh Manager and is executed directly from the manager server.

Launch it from a terminal using:

sudo /var/ossec/bin/wazuh-logtest

After starting, you’ll see an interactive prompt waiting for log input.

Typical output resembles:

Starting wazuh-logtest...

Type one log per line.

If the utility fails to start, first verify that the Wazuh Manager service is running and that your account has sufficient privileges.

Using wazuh-logtest

Once launched, Logtest remains in interactive mode until you exit.

The general workflow is straightforward:

Start wazuh-logtest.
Paste a log entry.
Press Enter.
Review the three analysis phases.
Modify your decoder or rule if necessary.
Repeat until the desired output is achieved.

Because the utility processes each log independently, you can rapidly iterate while developing custom detection logic.

Running Logtest with Appropriate Permissions

On most Linux installations, Logtest should be executed using an account with administrative privileges.

For example:

sudo /var/ossec/bin/wazuh-logtest

Running without sufficient permissions may prevent the utility from accessing loaded rules or configuration files, resulting in incomplete or misleading output.

If you’ve recently modified decoder or rule files, ensure the Wazuh Manager has been restarted or reloaded so Logtest uses the latest configuration.

Testing a Simple Log

One of the best ways to understand Logtest is by testing a basic syslog message.

For example:

Jul 20 12:31:18 web01 sshd[2031]: Failed password for invalid user admin from 192.168.1.50 port 52184 ssh2

After pressing Enter, Logtest begins analyzing the event immediately.

Entering Log Entries

Log entries can be pasted directly into the interactive prompt.

Examples include:

Linux syslog
Windows Event Logs
Apache access logs
Nginx logs
Firewall logs
Custom application logs
Cloud service logs
JSON events

Each submitted line is analyzed independently, allowing you to test many variations quickly.

Reading the Returned Analysis

After processing a log, Logtest displays output similar to:

Phase 1: Completed pre-decoding

Phase 2: Completed decoding

Phase 3: Rule evaluation finished

The output also identifies:

Matching decoder
Extracted fields
Matching rules
Alert severity
Rule description

If processing stops before Phase 3, the displayed output usually indicates exactly where the problem occurred.

Testing JSON Logs

Modern environments increasingly generate structured JSON logs rather than traditional syslog messages.

Fortunately, Wazuh Logtest fully supports JSON parsing when appropriate decoders are available.

Example:

{
  "event":"login_failed",
  "username":"alice",
  "src_ip":"192.168.1.100",
  "application":"vpn"
}

Testing JSON logs is especially useful when integrating:

Cloud providers
Kubernetes
Container platforms
SaaS applications
Custom APIs

If you’re working extensively with structured logs, see How to Parse Flattened Nested Keys and Arrays in Wazuh JSON Logs.

JSON Log Parsing

When a JSON decoder matches successfully, Wazuh automatically parses the object’s fields instead of treating the event as plain text.

This allows rules to reference individual attributes directly rather than relying on regular expressions.

Nested Field Extraction

Complex JSON documents often contain nested objects.

For example:

{
  "user":{
      "name":"alice",
      "department":"IT"
  },
  "network":{
      "src_ip":"10.10.10.25"
  }
}

Logtest lets you verify whether nested values are extracted correctly before writing rules that depend on them.

Validating Decoded Fields

After parsing completes, verify that every expected field appears in the decoded output.

Pay particular attention to:

IP addresses
Usernames
Event IDs
File paths
Hostnames
Status codes
Process names

Missing fields usually indicate decoder problems rather than rule issues.

Testing Custom Decoders

One of the primary uses of Logtest is validating custom decoders.

Instead of deploying changes into production, administrators can repeatedly test sample logs until every field is extracted correctly.

For a complete walkthrough of decoder development, see Wazuh Decoder Guide.

Confirming Decoder Matches

The output identifies the decoder that matched the log.

For example:

decoder: custom-authentication

If no decoder appears, either:

no decoder matched the log format, or
an earlier decoder consumed the event unexpectedly.

Verifying Extracted Fields

Once a decoder matches, inspect every extracted field.

Confirm that:

values are complete
regular expressions captured the intended text
numeric values remain intact
timestamps are accurate
usernames and IP addresses are parsed correctly

Small regex mistakes often become immediately obvious during this step.

Detecting Decoder Conflicts

Occasionally, multiple decoders can match similar log formats.

Symptoms include:

incorrect decoder selection
missing fields
partially parsed logs
unexpected downstream rule behavior

Logtest makes these conflicts much easier to identify before they impact production alerts.

Testing Custom Rules

After decoding succeeds, verify that your detection rules behave exactly as intended.

This includes validating:

rule conditions
severity levels
inheritance
parent-child relationships
alert descriptions

For a deeper guide, see How to Create Custom Detection Rules in Wazuh (With Examples).

Confirming Parent and Child Rule Matches

Many custom rules depend on parent-child relationships.

Logtest clearly shows which parent rule matched first and which child rule ultimately generated the alert.

This makes debugging inheritance logic much easier.

For more advanced examples, see How to Map Complex Log Fields Using Wazuh Parent Child Rules.

Checking Rule Inheritance

When child rules inherit conditions from parent rules, Logtest verifies whether the inheritance chain functions correctly.

Common issues include:

incorrect parent IDs
missing decoder references
conflicting field conditions
improperly ordered rules

Verifying Alert Levels and Descriptions

Finally, confirm that the generated alert matches your expectations.

Review:

alert level
rule description
groups
MITRE ATT&CK techniques
compliance mappings
decoded fields

A correctly functioning rule should produce an alert that accurately reflects the event’s security significance.

Understanding Wazuh Logtest Output

One of Logtest’s greatest strengths is the detailed information it exposes during every stage of event processing.

Rather than simply indicating whether a rule matched, it shows exactly how Wazuh interpreted the log, which decoder processed it, and why a specific rule generated an alert.

Learning to interpret this output dramatically simplifies troubleshooting and custom rule development.

Phase 1 Output

Phase 1 performs pre-decoding by extracting common metadata from the raw log before decoder evaluation begins.

Typical output includes:

timestamp
hostname
program name
raw message

If these values appear incorrect, the issue often originates with the log format rather than the decoder itself.

Timestamp

The timestamp is extracted from the log header whenever possible.

Verify that:

the date is correct
the time is accurate
the expected timezone is used

Malformed timestamps can prevent accurate event correlation.

Hostname

The hostname identifies the originating system.

Confirm that Logtest correctly identifies:

server names
endpoint names
container hosts
network devices

Missing hostnames are common in application-generated logs that omit syslog headers.

Program Name

The program name identifies the application responsible for generating the event.

Examples include:

sshd
nginx
apache2
sudo
kernel
custom applications

Many decoders rely on this value when determining which parser to apply.

Raw Log

The raw log displays the original message submitted to Logtest.

Always verify that:

no characters were accidentally omitted
line breaks were preserved appropriately
escape sequences remain intact

Even small formatting differences can affect decoder matching.

Phase 2 Output

Phase 2 displays the decoder responsible for parsing the event.

This phase is often the most important when developing custom detection content.

Decoder Name

The decoder name identifies which decoder successfully parsed the log.

Example:

decoder: apache-accesslog

If the decoder is not the one you expected, review decoder ordering and matching conditions.

Extracted Fields

Logtest lists every field extracted by the decoder.

Typical fields include:

srcip
dstip
username
action
process
file
status
event_id

Verify every field before proceeding to rule development.

Decoder Hierarchy

Some decoders inherit from parent decoders.

Logtest helps visualize this hierarchy by showing which decoder chain ultimately processed the log.

This is especially useful when debugging layered decoders or custom parsing logic.

Phase 3 Output

Phase 3 evaluates the decoded event against every applicable rule.

If conditions are satisfied, Logtest displays the resulting alert information.

Rule ID

Each matching rule includes its unique rule ID.

Example:

Rule id: 5710

This allows you to quickly locate the corresponding XML rule definition.

Alert Level

The alert level indicates the severity assigned by the matching rule.

Typical values range from informational events to high-severity security incidents.

Review the assigned level to ensure it reflects the actual risk presented by the event.

Description

The rule description provides a human-readable explanation of why the alert was generated.

Descriptions should be:

concise
meaningful
operationally useful

Groups

Groups classify alerts into logical categories.

Examples include:

authentication
web
malware
firewall
compliance
attack

Groups help analysts filter and correlate alerts within the Wazuh Dashboard.

MITRE ATT&CK Mappings

Many built-in Wazuh rules include mappings to the MITRE ATT&CK framework.

These mappings help analysts understand the adversary techniques associated with an event and support threat hunting and reporting.

Compliance Tags

Wazuh rules may also include compliance mappings for standards such as:

PCI DSS
HIPAA
GDPR
NIST
CIS Controls

These tags simplify compliance reporting by linking security events to applicable regulatory frameworks.

Common Wazuh Logtest Commands

Although most users rely on interactive mode, wazuh-logtest supports several options that make testing faster and more efficient during rule development.

Interactive Mode

Interactive mode is the most commonly used method.

Start it with:

sudo /var/ossec/bin/wazuh-logtest

Paste one log at a time and immediately review the resulting analysis.

This approach is ideal when iteratively refining decoders and rules.

Reading Logs from Files

For larger testing sessions, administrators often copy representative log samples from existing log files and submit them sequentially to Logtest.

This allows multiple real-world events to be validated without waiting for live systems to reproduce them.

When working with extensive datasets, maintain a library of sanitized sample logs that can be reused whenever decoder or rule changes are introduced.

Testing Multiple Log Samples

A single decoder should rarely be validated against only one event.

Instead, test multiple examples that include:

expected matches
malformed logs
edge cases
alternate message formats
unexpected values

This broader testing helps ensure your detection logic remains reliable under real-world conditions.

Useful Command-Line Options

Depending on your Wazuh version, wazuh-logtest provides options for displaying usage information and other runtime behavior.

A quick way to review available options is:

/var/ossec/bin/wazuh-logtest --help

Consult the official Wazuh documentation for version-specific options, as supported flags may vary between releases.

Exiting Logtest

When you’re finished testing, simply exit the interactive session using:

Ctrl + C

No configuration changes are made when closing Logtest, making it safe to use repeatedly during decoder and rule development without affecting your production environment.

Troubleshooting Common Wazuh Logtest Problems

Even experienced Wazuh administrators occasionally encounter unexpected Logtest results.

Fortunately, because Logtest exposes each stage of the detection pipeline, most issues can be isolated quickly by identifying where processing stops.

The following are some of the most common problems and how to resolve them.

No Decoder Matches

If Logtest completes Phase 1 but reports no matching decoder, Wazuh was unable to find a parser that recognizes the log format.

Typical output may resemble:

Phase 2: No decoder matched.

This usually indicates an issue with decoder configuration rather than the detection rules.

Incorrect Decoder Order

Wazuh evaluates decoders in a defined order. A generic decoder placed before a more specific one can prevent the intended decoder from ever being evaluated.

Review:

Parent decoder placement
Child decoder ordering
Decoder inheritance
Decoder file loading order

Prematch Failures

Many decoders rely on <prematch> expressions before evaluating regular expressions.

If the prematch condition fails, Wazuh skips the decoder entirely.

Verify that your prematch pattern accurately reflects the log format.

Regex Issues

Regular expressions are one of the most common causes of decoder failures.

Check for:

Missing escape characters
Incorrect anchors (^ or $)
Greedy matching
Typographical errors
Unexpected whitespace

If you’re troubleshooting decoder syntax, see How to Fix “Field Already Defined” Syntax Errors in Wazuh Decoders.

Wrong Rule Triggered

Sometimes decoding succeeds, but an unexpected rule generates the alert.

This usually results from rule ordering or inheritance rather than decoder problems.

Parent-Child Rule Hierarchy

Many child rules inherit conditions from parent rules.

If the wrong parent matches, every downstream child rule may behave unexpectedly.

Review:

Parent rule IDs
<if_sid>
<if_group>
<if_matched_sid>

For more information, see How to Map Complex Log Fields Using Wazuh Parent Child Rules.

Rule Ordering

Rules are evaluated sequentially.

If a broad rule matches before a more specific rule, the resulting alert may not reflect your intended detection logic.

Always place highly specific rules after their corresponding parent rules.

Rule Overwrite Conflicts

Custom rules that overwrite built-in rules can unintentionally alter detection behavior.

Ensure:

Rule IDs are unique when appropriate.
Overwrites are intentional.
Dependencies remain valid after modification.

For additional guidance, see How to Safely Overwrite Local Rule IDs Without Wazuh Conflicts.

Missing Fields

If decoding succeeds but expected fields are absent, the decoder likely failed to extract part of the log.

Decoder Extraction Problems

Review the decoder’s regular expressions and field mappings.

Verify that:

Every capture group exists.
Fields are assigned correctly.
Optional values are handled properly.

JSON Parsing Errors

Malformed JSON can prevent Wazuh from extracting nested fields.

Common causes include:

Missing commas
Invalid quotation marks
Incorrect nesting
Unsupported formatting

If you’re working with structured logs, see How to Parse Flattened Nested Keys and Arrays in Wazuh JSON Logs.

Regex Capture Group Mistakes

Capture groups determine which values become extracted fields.

A missing parenthesis or incorrect group order can cause fields to appear empty or contain incorrect data.

Testing with multiple log variations helps uncover these issues early.

Logtest Produces No Alert

Occasionally, decoding succeeds but Phase 3 finishes without generating an alert.

This means no rule conditions were satisfied.

Rule Level 0

Rules configured with alert level 0 intentionally suppress alerts.

Although they participate in rule evaluation, they do not generate visible alerts.

Review the rule definition to determine whether this behavior is expected.

Rule Conditions Not Satisfied

Your decoder may have extracted fields correctly, but the rule conditions still weren’t met.

Verify:

Field values
Regular expressions
<match> elements
<field> conditions
Parent rule dependencies

Testing multiple log samples often helps identify overly restrictive conditions.

Missing Decoder Dependencies

Some rules require a specific decoder before they can execute.

If the expected decoder never matches, the rule will never be evaluated.

Confirm that the decoder name referenced by the rule matches the decoder shown in Phase 2.

Unexpected Decoder Selected

Occasionally, Logtest selects a decoder that technically matches the log but isn’t the one you intended.

This often leads to incorrect field extraction and unexpected rule behavior.

Decoder Precedence

Wazuh generally evaluates decoders from the most applicable loaded definitions based on matching criteria.

Broad matching patterns can unintentionally capture logs before a more specific decoder has a chance to process them.

Whenever possible, make your decoder matching expressions as specific as practical.

Prematch Conflicts

Multiple decoders with similar <prematch> conditions can compete for the same logs.

Refining the prematch expression to target a unique portion of the log often resolves these conflicts.

Decoder Inheritance Issues

Improper parent-child relationships can cause Wazuh to stop processing before the intended child decoder executes.

Verify that:

Parent decoders match successfully.
Child decoders reference the correct parent.
Inheritance chains are complete.
Decoder names are spelled correctly.

Developing and validating decoder hierarchies incrementally with Logtest is the most effective way to identify inheritance issues before deploying changes to production.

Best Practices for Using Wazuh Logtest

While Wazuh Logtest is straightforward to use, following a few proven practices can significantly improve the quality of your custom decoders and detection rules.

These practices help reduce false positives, prevent missed detections, and make future maintenance much easier.

Test Every Decoder Before Deployment

Never deploy a new or modified decoder without validating it in Logtest first.

A successful decoder should:

Match the intended log format.
Extract every required field.
Ignore unrelated log formats.
Produce consistent results across multiple log samples.

Testing before deployment allows you to identify parsing errors in minutes instead of discovering them after alerts fail in production.

Validate Rules Incrementally

When developing custom rules, avoid creating an entire rule hierarchy before testing.

Instead:

Verify the decoder matches.
Test the parent rule.
Test each child rule individually.
Validate correlation rules last.

Incremental testing makes it much easier to identify the exact change that introduced an issue.

If you’re building custom detections, see How to Create Custom Detection Rules in Wazuh (With Examples).

Use Representative Production Logs

Testing with simplified or manually created logs often misses formatting variations that occur in production.

Whenever possible, collect sanitized samples from:

Production servers
Firewalls
VPN appliances
Cloud services
Web servers
Endpoint agents

Representative logs provide much higher confidence that your decoder will perform correctly after deployment.

Test Edge Cases and Malformed Logs

Don’t limit testing to perfectly formatted events.

Also validate:

Missing fields
Empty values
Unexpected whitespace
Invalid timestamps
Truncated messages
Corrupted JSON
Alternate software versions

Testing edge cases helps ensure your detection content behaves predictably even when logs are incomplete or malformed.

Keep Decoders Modular

Large monolithic decoders are difficult to maintain and troubleshoot.

Instead:

Create reusable parent decoders.
Build specialized child decoders.
Separate unrelated log formats.
Keep regular expressions focused and readable.

Modular decoder design improves maintainability and reduces unintended parser conflicts.

For additional guidance, see How to Map Complex Log Fields Using Wazuh Parent Child Rules.

Verify Parent-Child Rule Relationships

Many detection issues stem from incorrectly configured rule hierarchies.

After every change, verify that:

Parent rules match first.
Child rules inherit the correct conditions.
Rule IDs are referenced correctly.
Alert levels remain appropriate.

Logtest clearly displays the matching rule sequence, making hierarchy validation much easier.

Document Expected Outputs

As your custom ruleset grows, maintain documentation describing what each test should produce.

For each sample log, record:

Expected decoder
Extracted fields
Matching rule ID
Alert level
Rule description

This documentation makes future regression testing much faster and helps new team members understand your detection logic.

Re-Test After Wazuh Upgrades

Upgrading Wazuh can introduce new built-in decoders, updated rules, or changes to parsing behavior.

After every upgrade:

Re-run Logtest against critical log samples.
Verify custom decoders still match.
Confirm rule IDs remain valid.
Check for changes in alert output.

Regression testing helps identify compatibility issues before they affect production monitoring.

If you’re planning an upgrade, see How to Upgrade a Wazuh Agent for agent-specific considerations.

Version Control Custom Rules and Decoders

Store all custom XML files in a version control system such as Git.

Benefits include:

Change history
Easy rollback
Code reviews
Team collaboration
Automated deployment
Traceability

Version control also makes it easier to compare Logtest results across different revisions of your detection content.

Automate Logtest Validation in CI/CD Pipelines

Organizations managing large Wazuh deployments often incorporate Logtest into their CI/CD workflows.

For example, a pipeline can:

Deploy updated decoder files to a test environment.
Execute Logtest against a library of sample logs.
Compare the output against expected results.
Reject changes that introduce parsing or rule regressions.

This approach supports detection-as-code practices and helps maintain consistent detection quality as your ruleset evolves.

Real-World Example

Scenario

A security operations team manages remote access for several hundred employees using a custom VPN appliance.

Although the appliance generates detailed authentication logs, its proprietary log format is not supported by Wazuh’s built-in decoders.

As a result, failed VPN logins are ingested as unstructured text, preventing analysts from creating reliable detection rules.

To address the issue, the team develops a custom parent decoder that identifies VPN authentication events based on a unique log prefix.

Several child decoders then extract important fields including the username, source IP address, connection status, and session ID.

Before deploying the decoder into production, the engineers use Wazuh Logtest to validate each stage of the parsing process.

Solution:

During Phase 1, they confirm that the log’s timestamp, hostname, and raw message are pre-decoded correctly.

In Phase 2, Logtest shows that the intended custom decoder is selected, but the extracted username field is empty.

By reviewing the decoder output, they discover a regular expression that fails to account for usernames containing hyphens.

After updating the regex and rerunning Logtest, the username is extracted successfully along with the remaining fields.

Next, the team creates a parent rule that matches all VPN authentication events and child rules that distinguish between successful logins, failed logins, and repeated authentication failures from the same source IP address.

Running the same sample logs through Logtest confirms that the correct parent and child rule IDs are triggered, inheritance behaves as expected, and the generated alerts use the appropriate severity levels and descriptive messages.

Finally, the engineers verify that the alerts include the expected decoder fields, rule groups, and compliance metadata before deploying the updated decoders and rules to production.

Result:

Because the configuration was thoroughly validated with Logtest, the rollout proceeds without unexpected parsing errors or missed detections.

Analysts immediately begin receiving actionable alerts for repeated VPN authentication failures, allowing them to investigate potential brute-force attacks more quickly.

Frequently Asked Questions (FAQ)

Question: What is Wazuh Logtest used for?

Wazuh Logtest is a diagnostic utility that simulates the Wazuh analysis engine.

It allows administrators to test log parsing, validate custom decoders, verify rule matching, and troubleshoot detection logic before deploying configuration changes into production.

Question: How does Wazuh Logtest work?

Logtest processes a submitted log through the same three phases used by the Wazuh Manager:

Pre-decoding
Decoder matching
Rule evaluation

After processing, it displays the selected decoder, extracted fields, matching rule IDs, alert level, and additional metadata, making it easy to determine where parsing or detection issues occur.

Question: Can Wazuh Logtest test custom decoders?

Yes. Testing custom decoders is one of the primary uses of Logtest.

It allows you to verify that the correct decoder matches the log and that all expected fields are extracted before deploying the decoder into production.

For additional guidance, see Wazuh Decoder Guide.

Question: Can I test custom rules with Wazuh Logtest?

Yes. After a decoder successfully parses a log, Logtest evaluates all applicable detection rules, allowing you to confirm rule IDs, alert levels, inheritance, and descriptions without generating live production events.

Question: What do the three Logtest phases mean?

The three phases represent the stages of the Wazuh analysis pipeline:

Phase 1: Extracts metadata such as timestamps, hostnames, and program names.
Phase 2: Matches a decoder and extracts structured fields.
Phase 3: Evaluates detection rules and determines whether an alert should be generated.

Reviewing each phase helps isolate parsing and rule-related issues quickly.

Question: Why doesn’t my decoder match?

Common causes include:

Incorrect <prematch> expressions
Regular expression errors
Improper decoder ordering
Incorrect parent decoder references
Unexpected log formatting

Logtest output usually indicates whether the failure occurs before or during decoder matching.

Question: Why isn’t my rule triggering?

If decoding succeeds but no alert is generated, check whether:

The rule conditions are satisfied.
Required fields were extracted.
Parent rule dependencies are met.
The rule is configured with an alert level of 0.
The decoder referenced by the rule matches the event.

Testing multiple representative log samples often helps identify overly restrictive rule conditions.

Question: Can Wazuh Logtest validate JSON logs?

Yes. Logtest supports JSON log validation when an appropriate decoder is available.

It can verify field extraction from nested objects, arrays, and structured data, making it particularly useful for cloud services, APIs, and containerized environments.

Question: Does Wazuh Logtest modify production alerts?

No. Logtest runs independently of normal event processing and does not generate production alerts, modify indexes, or affect existing monitoring.

It is designed specifically as a safe testing environment for validating decoders and detection rules.

Question: Should I use Wazuh Logtest before every rule change?

Yes. Validating every decoder and rule modification before deployment is considered a best practice.

Routine testing helps identify parsing errors, verify rule behavior, reduce false positives, and ensure that important security events continue to generate alerts after configuration changes.

Conclusion

Wazuh Logtest is an essential utility for anyone developing, customizing, or troubleshooting Wazuh detection content.

By simulating the same analysis pipeline used by the Wazuh Manager, it provides immediate visibility into how logs are pre-decoded, parsed by decoders, and evaluated against detection rules.

Whether you’re creating custom decoders, refining parent-child rule hierarchies, or troubleshooting why an alert isn’t firing, Logtest allows you to validate your work before it reaches production.

This proactive approach reduces deployment risk, shortens troubleshooting time, and helps ensure your security monitoring remains accurate and reliable.

Incorporating Wazuh Logtest into your regular workflow, especially before deploying new rules, upgrading Wazuh, or introducing new log sources, can significantly improve the quality of your detection engineering.

Combined with representative test data, version-controlled configurations, and automated validation where possible, routine Logtest usage helps reduce false positives, eliminate parsing errors, and build a more resilient Wazuh deployment.

For additional learning, the official Wazuh documentation includes detailed references for Logtest usage and rule testing.

How to Use Wazuh Logtest

What Is Wazuh Logtest?

Definition of Wazuh Logtest

How Logtest Fits into the Wazuh Detection Pipeline

Why Security Analysts Use Logtest

Benefits of Validating Logs Before Deployment

How Wazuh Logtest Works

Overview of the Log Analysis Process

Phase 1: Log Pre-Decoding

Phase 2: Decoder Matching

Phase 3: Rule Evaluation

Understanding the Output at Each Phase

Prerequisites

Installed and Running Wazuh Manager

Administrative Access

Existing Decoders and Rules

Sample Logs Available for Testing

Understanding Wazuh Rule IDs and Decoder Hierarchy

How to Run Wazuh Logtest

Launching Logtest

Using wazuh-logtest

Running Logtest with Appropriate Permissions

Testing a Simple Log

Entering Log Entries

Reading the Returned Analysis

Testing JSON Logs

JSON Log Parsing

Nested Field Extraction

Validating Decoded Fields

Testing Custom Decoders

Confirming Decoder Matches

Verifying Extracted Fields

Detecting Decoder Conflicts

Testing Custom Rules

Confirming Parent and Child Rule Matches

Checking Rule Inheritance

Verifying Alert Levels and Descriptions

Understanding Wazuh Logtest Output

Phase 1 Output

Timestamp

Hostname

Program Name

Raw Log

Phase 2 Output

Decoder Name

Extracted Fields

Decoder Hierarchy

Phase 3 Output

Rule ID

Alert Level

Description

Groups

MITRE ATT&CK Mappings

Compliance Tags

Common Wazuh Logtest Commands

Interactive Mode

Reading Logs from Files

Testing Multiple Log Samples

Useful Command-Line Options

Exiting Logtest

Be First to Comment

Leave a Reply Cancel reply