wazuhcoverage

wazuhcoverage measures what happens to events captured in Wazuh JSON archives. It classifies each event by decoder/rule outcome, groups unresolved events into actionable findings, derives auditable reliability and efficiency metrics, 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

For machine-readable metrics, use wazuhcoverage --json archive.json.gz. Multiple archives are emitted as JSON Lines. For an interactive two-tab report, use wazuhcoverage --html report.html archive.json.gz. The generated file contains the report HTML, CSS and application JavaScript; pinned Pico CSS and ECharts resources are loaded from jsDelivr. 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.

Metrics

The statistics report derives five independent measurements: malformed input, decoder failure, replay-confirmed uncovered coverage, below-threshold processing, and unresolved outcomes. Every metric retains its numerator and denominator; replay-dependent measurements are reported as unavailable when the evidence is incomplete rather than silently becoming zero.

The same measurements are available by log type with both the local rate and the log type's contribution to the estate-wide condition. The human report shows the largest contributors, while the Python API and --json output retain the complete per-log-type set.

Metrics begin at the archive boundary. They do not measure events that should have been generated but never reached the archive, and they are not combined into a composite health or coverage score. See METRICS.md for formulas and interpretation limits.

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, verification, and metric APIs.
• Metrics — formulas, replay semantics, log-type dimensions, and interpretation limits.
• 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.