rsigma_eval/
lib.rs

1//! # rsigma-eval
2//!
3//! Evaluator for Sigma detection and correlation rules.
4//!
5//! This crate consumes the AST produced by [`rsigma_parser`] and evaluates it
6//! against events in real time using a compile-then-evaluate model.
7//!
8//! ## Architecture
9//!
10//! - **Detection rules** (stateless): compiled once into optimized matchers,
11//!   each event is matched with zero allocation on the hot path.
12//! - **Correlation rules** (stateful): time-windowed aggregation over detection
13//!   matches, supporting `event_count`, `value_count`, `temporal`,
14//!   `temporal_ordered`, `value_sum`, `value_avg`, `value_percentile`,
15//!   and `value_median`.
16//!
17//! ## Quick Start — Detection Only
18//!
19//! ```rust
20//! use rsigma_parser::parse_sigma_yaml;
21//! use rsigma_eval::{Engine, Event};
22//! use serde_json::json;
23//!
24//! let yaml = r#"
25//! title: Detect Whoami
26//! logsource:
27//!     product: windows
28//!     category: process_creation
29//! detection:
30//!     selection:
31//!         CommandLine|contains: 'whoami'
32//!     condition: selection
33//! level: medium
34//! "#;
35//!
36//! let collection = parse_sigma_yaml(yaml).unwrap();
37//! let mut engine = Engine::new();
38//! engine.add_collection(&collection).unwrap();
39//!
40//! let event_val = json!({"CommandLine": "cmd /c whoami"});
41//! let event = Event::from_value(&event_val);
42//! let matches = engine.evaluate(&event);
43//! assert_eq!(matches.len(), 1);
44//! ```
45//!
46//! ## Quick Start — With Correlations
47//!
48//! ```rust
49//! use rsigma_parser::parse_sigma_yaml;
50//! use rsigma_eval::{CorrelationEngine, CorrelationConfig, Event};
51//! use serde_json::json;
52//!
53//! let yaml = r#"
54//! title: Login
55//! id: login-rule
56//! logsource:
57//!     category: auth
58//! detection:
59//!     selection:
60//!         EventType: login
61//!     condition: selection
62//! ---
63//! title: Many Logins
64//! correlation:
65//!     type: event_count
66//!     rules:
67//!         - login-rule
68//!     group-by:
69//!         - User
70//!     timespan: 60s
71//!     condition:
72//!         gte: 3
73//! level: high
74//! "#;
75//!
76//! let collection = parse_sigma_yaml(yaml).unwrap();
77//! let mut engine = CorrelationEngine::new(CorrelationConfig::default());
78//! engine.add_collection(&collection).unwrap();
79//!
80//! for i in 0..3 {
81//!     let v = json!({"EventType": "login", "User": "admin"});
82//!     let event = Event::from_value(&v);
83//!     let result = engine.process_event_at(&event, 1000 + i);
84//!     if i == 2 {
85//!         assert_eq!(result.correlations.len(), 1);
86//!     }
87//! }
88//! ```
89
90pub mod compiler;
91pub mod correlation;
92pub mod correlation_engine;
93pub mod engine;
94pub mod error;
95pub mod event;
96pub mod matcher;
97pub mod pipeline;
98pub mod result;
99
100// Re-export the most commonly used types and functions at crate root
101pub use compiler::{
102    CompiledDetection, CompiledDetectionItem, CompiledRule, compile_rule, evaluate_rule,
103};
104pub use correlation::{
105    CompiledCondition, CompiledCorrelation, EventBuffer, EventRef, EventRefBuffer, GroupByField,
106    GroupKey, WindowState,
107};
108pub use correlation_engine::{
109    CorrelationAction, CorrelationConfig, CorrelationEngine, CorrelationEventMode,
110    CorrelationResult, ProcessResult, TimestampFallback,
111};
112pub use engine::Engine;
113pub use error::{EvalError, Result};
114pub use event::Event;
115pub use matcher::CompiledMatcher;
116pub use pipeline::{
117    Pipeline, apply_pipelines, merge_pipelines, parse_pipeline, parse_pipeline_file,
118};
119pub use result::{FieldMatch, MatchResult};
rsigma_eval/lib.rs

rsigma_eval/
lib.rs
