wazuhcoverage

wazuhcoverage measures what happens to events captured in Wazuh JSON archives. It classifies each event by decoder/rule outcome, groups uncovered events into actionable findings, and keeps one real sample per finding for replay through wazuh-logtest.

It reads archives.json and archives.json.gz produced when Wazuh JSON archiving is enabled and never modifies them. See the Wazuh documentation for archiving event logs.

When a usable Wazuh manager is available, wazuhcoverage can replay representative findings through wazuh-logtest and report what the current ruleset does with them. Without a manager it remains an offline archive analyzer.

Installation

Python 3.9 or newer is supported; Python 3.10 or newer is recommended.

For command-line use:

pipx install wazuhcoverage

For use as a Python library:

python -m pip install wazuhcoverage

Manager replay is an optional extra. It requires Linux, Python 3.10 or newer, and access to a running Wazuh manager:

pipx install "wazuhcoverage[logtest]"

The base package installs DuckDB for archive analysis and drain3 for finding grouping. Dependency constraints and their rationale are documented in design notes.

Quick start

Analyze one archive:

wazuhcoverage /var/ossec/logs/archives/2026/Sep/ossec-archive-18.json.gz

Analyze a set of archives:

wazuhcoverage "/var/ossec/logs/archives/2026/**/*.json.gz"

Read from standard input:

cat logs.json | wazuhcoverage
ssh manager "cat /var/ossec/logs/archives/2026/Sep/ossec-archive-18.json.gz" | wazuhcoverage

Run wazuhcoverage --help for the short CLI summary. Target resolution, stdin behaviour, strict parsing, exit codes, output streams, and replay options are documented in docs/CLI.md.

Coverage model

Every parsed event lands in exactly one observed bucket:

The CLI reads <alerts><log_alert_level> from /var/ossec/etc/ossec.conf when the local manager configuration is available. Otherwise it assumes Wazuh's default threshold of 3. The report shows both the threshold and its source before the statistics. The Python API keeps the threshold explicit for callers analysing archives elsewhere.

no_alerting_rule needs care. A rule-less archive record does not, by itself, prove that no rule was evaluated. Wazuh can produce the same observable archive state for events that require different interpretations. When replay is available, wazuhcoverage uses wazuh-logtest to refine the result. See CAVEATS.md before treating coverage numbers as ground truth.

Findings

Raw event counts are usually too noisy to act on directly. wazuhcoverage therefore groups dropped events into findings.

below_threshold events group by rule ID. no_decoder and no_alerting_rule events group by log type and a mined message template. Each finding contains its event count, affected agents, observed time range, decoder/rule information where available, a message pattern, and one real source log.

The sample is retained for validation and replay rather than reconstructed from parsed fields. Grouping is deterministic for the same archive. The mining strategy, measurements, and trade-offs are documented in DESIGN.md.

Manager replay

If the logtest extra is installed and the manager socket is usable, the CLI automatically replays representative findings. This can distinguish several states that the archive alone cannot safely separate, including genuinely uncovered events and events matched by a level-0 rule.

Replay answers for the manager being queried now, not necessarily the manager configuration that originally wrote the archive. It also cannot reproduce every stateful rule from one representative event. See CAVEATS.md for the interpretation limits and the Wazuh references behind them.

For Wazuh itself, refer to the upstream alert-threshold documentation, rules classification, wazuh-logtest reference, wazuh-analysisd reference, and log collection documentation.

Documentation

• Command-line reference — targets, streams, report semantics, exit codes, and replay behaviour.
• Python API — analysis models and verification API.
• Caveats — Wazuh behaviours that affect interpretation.
• Design notes — implementation rationale, template-mining measurements, and dependency constraints.
• Third-party software — direct dependency license references.

Development

python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check .
python -m ruff format --check .

License

GNU General Public License version 2 only. See LICENSE. Direct dependencies retain their respective licenses; see the third-party software notice for license references.