rsigma rule hygiene

Flag rule hygiene and retirement candidates in one report, the lifecycle phase a mature detection program reviews on a retirement cadence.

Synopsis

rsigma rule hygiene --rules <PATH>... [OPTIONS]

Description

rule hygiene assembles the raw signals RSigma already produces into a single report of retirement and clean-up candidates. Mature detection programs treat rule management and maintenance as ongoing work (see Elastic’s DEBMM and the SANS detection engineering lifecycle): without a cull, the catalog fills with silent, noisy, unowned, and stale rules. This command surfaces those candidates.

It runs no event evaluation unless --corpus is set. The static signals read straight off the parsed rules; with --corpus, the command replays the corpus through the engine for per-rule fire counts; the silence and noisy signals also join a Prometheus snapshot or endpoint; the broken-coverage signal joins a field-observability snapshot. It is an offline rule-group command with no daemon hot-path involvement.

Only -r/--rules is required. The static signals (untagged, no-owner, incomplete-ads, deprecated/stale) report from the rules alone; the silence and noisy signals need --metrics or --corpus; the broken-coverage signal needs --fields.

Signals

Inputs

At least one of --metrics or --corpus is required for the silent and noisy signals; the static signals need only --rules.

The Prometheus join inherits the caveat documented in Metrics: rule_title is not guaranteed unique, so when two rules share a title their counters add together. The shared reader is the same one rule scorecard uses.

The broken-coverage rollup needs each rule’s full referenced-field set, so it joins the snapshot’s missing field names against the fields extracted from --rules. Generate the snapshot from the same rule set so the field names line up.

Flags

The global --output-format applies: table (the TTY default) renders the flagged rules under a per-signal summary, json emits the full report document, and ndjson/csv/tsv emit one row per flagged rule.

Report

The JSON document (--output-format json) has a stable shape:

• summary: total, detection, and correlation rule counts, the flagged count, which sources contributed, and a per-signal count.
• rules[]: per flagged rule, its title, id, kind, the signals it tripped, fire count and last-fired where known, owner, status, and tags.
• the per-signal lists never_fired, noisy, untagged, no_owner, incomplete_ads, broken_coverage, and stale_status.

--report writes the same JSON document to a file regardless of the chosen output format.

Exit codes

Examples

Report from the rules alone (static signals)

rsigma rule hygiene --rules ./rules

Add production fire volume for silence and noise

rsigma rule hygiene --rules ./rules --metrics http://localhost:9090/metrics

Use a replayed corpus instead of Prometheus (offline)

rsigma rule hygiene --rules ./rules --corpus ./corpus

Add broken field coverage from a field-observability snapshot

rsigma rule hygiene --rules ./rules \
    --metrics http://localhost:9090/metrics \
    --fields fields.json

Gate CI on rules silent longer than a year

rsigma rule hygiene --rules ./rules --metrics metrics.txt \
    --silent-threshold 365d --fail-on silent

See also

• Rule Hygiene for the retirement-cadence workflow and how each input feeds each signal.
• rule coverage shares the ATT&CK tag extraction behind the untagged signal; rule scorecard is the quantitative keep/tune/retire verdict this report complements.
• Observability for generating the field-observability snapshot.
• Configuration for the hygiene config section.
• Exit Codes reference for the canonical table.