rsigma engine daemon🔗

Run as a long-running daemon with hot-reload, health checks, and Prometheus metrics.

Synopsis🔗

rsigma engine daemon [OPTIONS] --rules <RULES>

Description🔗

Loads rules and pipelines, opens an event source, evaluates events as they arrive, fans the detections out to one or more sinks, and stays alive until it receives SIGTERM/SIGINT. Reloads rules and pipelines on file change, SIGHUP, or POST /api/v1/reload. Exposes Prometheus metrics, REST control endpoints, and OTLP log ingestion on the same --api-addr.

This is the long-running counterpart of engine eval. Use it when you need state to survive restarts, hot-reload across rule changes, or a Prometheus-scrapeable detection engine.

For narrative coverage see Streaming Detection. For NATS-specific operations (auth, replay, consumer groups, DLQ) see NATS Streaming.

Flags🔗

Required🔗

Event input🔗

Output sinks and DLQ🔗

Pipelines and dynamic sources🔗

Post-evaluation enrichment🔗

The enrichers file accepts max_concurrent_enrichments: <N> at the top level (default 16) plus a list of enricher entries, each declaring kind: detection | correlation, a primitive type: (template / lookup / http / command), an inject_field, and primitive-specific keys (template, url / headers / cache_ttl, command, source / extract / default, ...). Cross-namespace template references are rejected at startup with a clear error pointing at the offending field.

API server🔗

TLS (requires the daemon-tls build feature)🔗

When TLS is configured, the daemon terminates TLS in-process for every protocol on --api-addr (HTTP REST API, /metrics, OTLP/HTTP, OTLP/gRPC). The negotiation advertises both h2 and http/1.1 via ALPN so legacy REST clients and modern gRPC clients share one socket.

Hot-reload: every reload trigger funnels through the daemon's central debounced reload task, so a single POST /api/v1/reload (cross-platform, including Windows), kill -HUP <pid> (Unix), or a YAML file change picked up by the file watcher rotates rules, pipelines, enrichers, and the TLS certificate in one pass. The active rustls::ServerConfig is swapped atomically via Arc<ArcSwap<…>>, so new handshakes pick up the rotated material without dropping inflight TLS connections. Failed reloads keep the previous certificate active, bump rsigma_reloads_failed_total, and log an error so a typo in the cert path cannot black-hole the listener.

Observability: the /metrics endpoint exposes rsigma_tls_certificate_expiry_seconds (signed; negative once the cert has expired) and rsigma_tls_active_connections. A single WARN is logged at startup (and after every reload) if the active certificate expires within 30 days.

See TLS deployment for a deeper dive, including ACME / sidecar reverse proxy alternatives that this feature replaces.

Correlation behavior🔗

State persistence🔗

Throughput🔗

NATS (requires the daemon-nats build feature)🔗

The auth methods are mutually exclusive. See NATS Streaming for the full operational guide.

Performance (advanced)🔗

Examples🔗

Minimal daemon: stdin → stdout🔗

rsigma engine daemon -r rules/

Reads NDJSON from stdin, writes detections to stdout. Default API on 0.0.0.0:9090.

HTTP ingest with persistent state🔗

rsigma engine daemon -r rules/ \
    --input http \
    --state-db /var/lib/rsigma/state.db \
    --pipeline ecs_windows

Accepts POST /api/v1/events for ingest; correlation state survives restarts.

NATS source + sink + DLQ🔗

NATS_CREDS=/etc/rsigma/nats.creds \
rsigma engine daemon -r /etc/rsigma/rules/ \
    --input "nats://nats.internal:4222/events.>" \
    --output "nats://nats.internal:4222/detections" \
    --dlq "file:///var/log/rsigma/dlq.ndjson" \
    --state-db /var/lib/rsigma/state.db \
    --buffer-size 50000 \
    --batch-size 128 \
    --drain-timeout 30 \
    --nats-require-tls \
    --api-addr 0.0.0.0:9090

Multi-output fan-out🔗

rsigma engine daemon -r rules/ \
    --output stdout \
    --output "file:///var/log/rsigma/detections.ndjson" \
    --output "nats://nats.internal:4222/detections.urgent"

HTTPS with mutual TLS🔗

rsigma engine daemon -r rules/ \
    --input http \
    --api-addr 0.0.0.0:9090 \
    --tls-cert /etc/rsigma/tls/server.crt \
    --tls-key  /etc/rsigma/tls/server.key \
    --tls-client-ca /etc/rsigma/tls/clients-ca.crt

Clients connecting to https://daemon:9090/v1/logs (OTLP/HTTP) or https://daemon:9090/api/v1/events (REST) must present a certificate signed by clients-ca.crt or the handshake is rejected. Rotate the server cert with cp new.crt /etc/rsigma/tls/server.crt && kill -HUP $(pidof rsigma) on Unix, or cp new.crt … && curl -X POST https://daemon:9090/api/v1/reload on any platform (including Windows, where SIGHUP does not exist).

Forensic replay from a NATS sequence🔗

rsigma engine daemon -r rules/ \
    --input "nats://localhost:4222/events.>" \
    --replay-from-sequence 1001 \
    --state-db /var/lib/rsigma/replay-state.db \
    --timestamp-fallback skip

--timestamp-fallback skip prevents wall-clock contamination of correlation windows when replaying old events.

Health and readiness🔗

Full HTTP API reference: HTTP API. All metric definitions: Prometheus metrics.

Shutdown🔗

SIGTERM and SIGINT trigger a graceful drain bounded by --drain-timeout. In-flight events are processed and acknowledged before the daemon exits. With --state-db, the final correlation state snapshot is written during shutdown.

Exit codes🔗

See also🔗

• Streaming Detection for the daemon walkthrough.
• NATS Streaming for auth, replay, consumer groups, and DLQ details.
• OTLP Integration for the OTLP receiver and agent recipes.
• Performance Tuning for --bloom-prefilter, --cross-rule-ac, --batch-size, and --buffer-size.
• Observability for the RUST_LOG targets, tracing spans, and metric alerting recipes.
• engine eval for the one-shot evaluation counterpart.