rsigma-eval

The detection and correlation engine. Compiles parsed Sigma rules into a matcher tree, evaluates events against them, runs correlation windows, and applies processing pipelines.

• docs.rs/rsigma-eval
• README
• crates.io/crates/rsigma-eval

When to use

• Run rules against events in an in-process embedding (no daemon, no I/O).
• Build a custom front-end on top of the engine (different input format, different sink shape).
• Reuse the matcher optimizer, pipeline machinery, or correlation engine in another tool.

For streaming I/O (stdin / HTTP / NATS / OTLP), source resolution, and hot-reload, layer rsigma-runtime on top.

Install

[dependencies]
rsigma-parser = "0.18.0"
rsigma-eval = "0.18.0"
serde_json = "1"   # only if you use the JsonEvent shim

Public surface

The full enum of modifiers, the matcher-optimizer constants, the rsigma.* custom-attribute table, and the bloom/cross-rule prefilters live in the crate README.

Minimum example: detection only

use rsigma_eval::{Engine, JsonEvent};
use rsigma_parser::parse_sigma_yaml;
use serde_json::json;

let yaml = r#"
title: Whoami
id: 8b1d8c97-5b3a-4d77-9b48-7c5f7c8b1a2a
logsource: { product: windows, category: process_creation }
detection:
    selection:
        CommandLine|contains: 'whoami'
    condition: selection
level: medium
"#;

let collection = parse_sigma_yaml(yaml)?;
let mut engine = Engine::new();
engine.add_collection(&collection)?;

let event = json!({ "CommandLine": "cmd /c whoami" });
let matches = engine.evaluate(&JsonEvent::borrow(&event));

assert_eq!(matches.len(), 1);
assert_eq!(matches[0].header.rule_title, "Whoami");

With a pipeline

Pipeline applies before compilation. The CLI’s -p flag wires this up; in code:

use rsigma_eval::Engine;
use rsigma_eval::pipeline::parse_pipeline;
use rsigma_parser::parse_sigma_yaml;

let pipeline = parse_pipeline(r#"
name: ecs_windows
priority: 20
transformations:
  - id: ecs_fields
    type: field_name_mapping
    mapping:
      CommandLine: process.command_line
    rule_conditions:
      - type: logsource
        product: windows
"#)?;

let collection = parse_sigma_yaml(rule_yaml)?;

let mut engine = Engine::new();
engine.add_pipeline(pipeline);   // priority sorted; multiple allowed
engine.add_collection(&collection)?;

After this, the rule sees ECS field names; an event with process.command_line matches.

Correlation

For stateful detections, use CorrelationEngine instead of the bare Engine. It owns both the rule set and the sliding-window state:

use rsigma_eval::{CorrelationConfig, CorrelationEngine, JsonEvent, ProcessResultExt};
use rsigma_parser::parse_sigma_yaml;

let collection = parse_sigma_yaml(yaml)?;

let mut correlator = CorrelationEngine::new(CorrelationConfig::default());
correlator.add_collection(&collection)?;

for raw in events {
    let evt = JsonEvent::borrow(&raw);
    let result = correlator.process_event(&evt);
    for m in result.detections() { /* detection match */ }
    for c in result.correlations() { /* correlation firing */ }
}

process_with_detections(event, Vec<EvaluationResult>) is the lower-overhead variant for hot loops (pre-compute detections in parallel, feed sequentially to correlation). CorrelationConfig enforces max_state_entries (default 100,000) and the 10-deep correlation-chain limit; see Security Hardening.

Custom attributes

Pipeline transformations can write rsigma.* attributes that the engine consumes (include_event, correlation_event_mode, max_correlation_events, …). Full table in Custom Attributes.

Performance knobs

Schema classification and routing live alongside the engine: SchemaClassifier::classify and classify_with_ambiguity recognize an event’s schema from declarative SchemaSignature predicates, explain reports why, and validate_schema_config statically checks a config. SchemaRouter builds one engine per pipeline-set, routes each event to its schema’s engine (deriving the event’s logsource from the schema for pruning), feeds one shared correlation store, and reports a per-schema pruning summary via schema_pruning_summary. See the Schema Signatures reference and the Schema Routing guide.

Engine::add_rule and add_compiled_rule are amortized O(1) per call (v0.12.0+), so a control-plane that ingests rules one at a time no longer pays an O(N) cost on every push. The bulk loaders (add_rules, extend_compiled_rules, add_collection) rebuild indexes exactly once per batch. If you enable set_cross_rule_ac(true), prefer the bulk loaders since the daachorse automaton has no incremental update.

Decision matrix in Performance Tuning. Verified Criterion numbers in Benchmarks.

Error handling

EvalError from thiserror. Variants include Parser (re-exports the parser errors), InvalidRegex, InvalidCidr, InvalidModifiers, UnknownRuleRef (correlation references a rule that wasn’t added), CorrelationCycle, and Base64. Each carries enough context to point operators at the offending rule.

See also

• Architecture for how Engine and CorrelationEngine fit into the broader runtime.
• Performance Tuning for the bloom and cross-rule AC knobs.
• rsigma-runtime for the streaming-runtime layer that wraps this crate.
• Custom Attributes for the rsigma.* namespace this crate consumes.
• rsigma-eval README for the full API surface.
• docs.rs/rsigma-eval.