Core Concepts

A short tour of the ideas you run into when working with RSigma. If you already know Sigma, skim for RSigma-specific details: eval vs daemon, pipelines, conversion, and the noun-led CLI. If you are new to Sigma, the primer below is enough to follow the rest of these docs; authoring depth lives on SigmaHQ.

What is Sigma?

Sigma is a vendor-agnostic YAML format for describing log-event detection rules. A rule declares:

• A logsource that names where the events come from (category: process_creation, product: windows, …).
• One or more selections that match field values, like CommandLine|contains: 'whoami'.
• A condition expression combining selections with and, or, not, and quantifiers (1 of selection_*, all of them).
• Metadata: title, id, level, tags, references, false positives, and so on.

SigmaHQ maintains a large community rule repository. RSigma implements the Sigma v2.1.0 specification and is tested against that corpus on every CI run. Authoring questions belong on SigmaHQ’s docs; runtime, conversion, and operational questions belong here.

The three kinds of rules

RSigma understands the full Sigma v2 family:

Loading a directory of YAML files yields one in-memory collection of all three. Evaluation and conversion operate on that collection as a whole.

Selections, modifiers, and conditions

A detection block looks like this:

detection:
    selection:
        EventID: 4625
        TargetUserName|endswith: '$'
    filter_ip:
        SourceAddress|cidr: '10.0.0.0/8'
    condition: selection and not filter_ip

The keys under detection are named selections. The condition line is a boolean expression over those names. Field modifiers such as endswith, cidr, contains, and re change how a field value is matched. RSigma implements the full Sigma modifier set; see the parser library reference for the complete list.

Two modes: eval vs daemon

RSigma offers two evaluation modes that share the same engine:

Rule of thumb: anything that runs in a terminal and exits is engine eval; anything that runs as a service is engine daemon.

See evaluating rules and streaming detection for full tutorials.

Processing pipelines

Pipelines rewrite rules before compilation so Sigma field names match your event schema. For example, CommandLine may become process.command_line (ECS) or a JSONB path in PostgreSQL.

name: My ECS Mapping
priority: 20
transformations:
  - id: ecs_fields
    type: field_name_mapping
    mapping:
      CommandLine: process.command_line
      Image: process.executable
    rule_conditions:
      - type: logsource
        product: windows

RSigma supports the pySigma-compatible transformation set and ships builtin pipelines (ecs_windows, sysmon) you can pass by name with -p. Multiple pipelines chain by priority. Dynamic pipelines can also fetch values from HTTP, files, commands, or NATS at load time; see processing pipelines.

Conversion backends

Instead of evaluating rules in process, rsigma backend convert emits backend-native queries for historical hunting:

New backends plug in via the Backend trait; see adding backends and the rule conversion guide.

Input formats

Events are accepted as JSON/NDJSON by default, with auto-detection across syslog, logfmt, CEF, EVTX, OTLP, and plain text. Several formats are feature-gated. See input formats for the full matrix and flags.

The command groups

The CLI is noun-led: every group is a noun, every leaf is a verb.

See the CLI reference for every subcommand.

Output

Detection and correlation both serialize as a flat EvaluationResult JSON object on stdout (NDJSON when streaming). Downstream consumers tell them apart by field presence: detections carry matched_fields, correlations carry correlation_type.

A detection match looks like this (default match detail):

{"rule_title":"...","rule_id":"...","level":"medium","tags":["..."],"matched_selections":["selection"],"matched_fields":[{"field":"...","value":"..."}]}

The event field is omitted unless --include-event is set or the rule enables rsigma.include_event. Optional header fields such as rule_id and level serialize as null when absent; empty custom_attributes and unset enrichments are omitted.

A correlation firing looks like this:

{
  "rule_title": "Brute Force",
  "rule_id": "...",
  "level": "high",
  "tags": ["..."],
  "correlation_type": "event_count",
  "group_key": [["User", "admin"]],
  "aggregated_value": 5.0,
  "timespan_secs": 300
}

events and event_refs appear only when correlation event mode is Full or Refs. The HTTP API reference and eval library docs cover the full field set.

Where to go next

• Tutorial path: quick start -> evaluating rules -> streaming detection.
• Reference path: CLI, linting rules, Prometheus metrics, feature flags.
• Architecture path: crate map and data flow, library API, contributing.