pySigma-backend-victorialogs 0.1.0

pySigma VictoriaLogs (LogsQL) backend

pySigma backend for VictoriaLogs (LogsQL)

Convert Sigma detection rules to LogsQL queries that run against VictoriaLogs.

Sigma rule (YAML)
        │
        ▼
   pySigma core
        │
        ▼
 VictoriaLogsBackend  ──►  field:="value" AND other:~"regex"

---

Install

The recommended way is via sigma-cli's plugin system:

pip install sigma-cli
sigma plugin install victorialogs

Or directly as a library:

pip install pysigma-backend-victorialogs

First query

sigma convert -t victorialogs path/to/rule.yml

Programmatic use:

from sigma.collection import SigmaCollection
from sigma.backends.victorialogs import VictoriaLogsBackend

rule = SigmaCollection.from_yaml("""
title: SSH login failure
logsource:
    product: linux
    service: auth
detection:
    sel:
        program: sshd
        message|contains: "Failed password"
    condition: sel
""")

print(VictoriaLogsBackend().convert(rule)[0])
# program:="sshd" AND message:~"Failed password"

See docs/getting_started.md for the full walkthrough including a local VictoriaLogs container.

---

Compatibility

Component	Supported versions
Python	3.10, 3.11, 3.12, 3.13, 3.14
pySigma	^1.1.0
VictoriaLogs	v1.50.0 (pinned by digest in CI)

CI pins victoriametrics/victoria-logs:v1.50.0 by sha256 digest for reproducibility; bumps follow the procedure in CONTRIBUTING.md. Older or newer VL versions are not actively tested but should work as long as they parse the LogsQL constructs listed in docs/mapping.md.

Mapping summary

Sigma feature	LogsQL output
field: value	field:="value"
field|contains: x	field:~"x" (regex)
field|startswith: x	field:="x"* (native prefix)
field|endswith: x	field:~"x$" (regex anchor)
field|re: pattern	field:~"pattern"
field|cidr: 10.0.0.0/8	field:ipv4_range("10.0.0.0/8")
field|cidr: ::1/128	field:ipv6_range("::1/128")
field|gte: 1024	field:>=1024
field|fieldref: other	field:eq_field(other)
field|exists: true	field:*
field: null	field:""
field IN [a, b]	field:in("a", "b")
event_count correlation	_time:Xm <search> | stats by (g) count() as event_count | filter event_count:>=N

Full reference: docs/mapping.md.

Pipelines

Sigma rules use a neutral field taxonomy (Image, CommandLine, EventID, …) that does not match how any specific log shipper writes records. Pick a pipeline that matches your ingestion path:

Pipeline	Targets	Renames
victorialogs	(no-op placeholder)	none
victorialogs_windows_eventlog	Winlogbeat / Vector ECS Windows ingest	EventID→winlog.event_id, EventData→winlog.event_data.*, channel selectors
victorialogs_journald	systemd-journal native fields	Image→_EXE, CommandLine→_CMDLINE, Message→MESSAGE, …
victorialogs_caddy	Caddy v2 JSON access logs	cs-method→request.method, cs-uri-*→request.uri, sc-status→status, …
victorialogs_suricata	Suricata EVE JSON	dst_ip→dest_ip, QueryName→dns.rrname, TlsServerName→tls.sni, …
victorialogs_podman	podman/docker journald CONTAINER_*	ContainerName→CONTAINER_NAME, ImageName→IMAGE_NAME, …

sigma convert -t victorialogs -p victorialogs_journald rule.yml
sigma convert -t victorialogs -p victorialogs_windows_eventlog rule.yml
sigma convert -t victorialogs -p victorialogs_caddy rule.yml

Each pipeline applies only to rules whose logsource matches its target (e.g. product: linux for journald, category: webserver for Caddy, category: network or product: zeek|suricata for the EVE pipeline); other rules pass through untouched. Stack pipelines with multiple -p flags when, for example, podman containers ship through journald.

Output formats

Format	Output
default	Plain LogsQL query strings (one per rule)
vmalert	vmalert rule group YAML (type: vlogs) for VictoriaLogs

vmalert (deploy as alerting rules)

sigma convert -t victorialogs -f vmalert -p victorialogs_journald \
    rules/*.yml > sigma-rules.yaml

The output is a single rule group ready to feed to vmalert pointed at a VictoriaLogs datasource:

vmalert \
    -datasource.url=http://victorialogs:9428 \
    -rule.defaultRuleType=vlogs \
    -rule=sigma-rules.yaml \
    -notifier.url=http://alertmanager:9093

Each Sigma rule becomes one alert with expr wrapped as <query> | stats count() as matches | filter matches:>0 (correlation rules already aggregate and pass through unwrapped). vmalert auto-prepends _time:<group_interval>, so the emitted expressions are time-agnostic by design — change the evaluation window via the group interval (default 5m) rather than editing every query. Sigma level maps to labels.severity and id to labels.sigma_id. Requires vmalert ≥ v1.93 (when type: vlogs was added). See docs/mapping.md §14 for the full mapping.

Limitations

• Temporal correlations (temporal, temporal_ordered) are unsupported — LogsQL has no native multi-event window join.
• -search.maxQueryLen defaults to 16 KiB; seven SigmaHQ rules emit queries above this. Raise the flag at VL startup if you need them: victoria-logs -search.maxQueryLen=524288 ...
• No native single-character wildcard — Sigma ? routes to regex.
• Case-sensitivity is the default (LogsQL :=).

Full details and workarounds: docs/limitations.md.

Documentation

• Getting started — install → first query → live VL.
• Mapping reference — exhaustive Sigma → LogsQL spec.
• Architecture — how the backend works (for contributors).
• Limitations — what we cannot do, and why.
• Security policy — threat model + reporting.
• Contributing — dev setup + Conventional Commits.

License

MIT © aris1009