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

CI pins victoriametrics/victoria-logs:v1.53.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

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:

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

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.

grafana_alerting (deploy as Grafana provisioned alert rules)

sigma convert -t victorialogs -f grafana_alerting \
    -O grafana_datasource_uid=<your-vl-uid> \
    rules/*.yml > /etc/grafana/provisioning/alerting/sigma.yaml

The output is an apiVersion: 1 provisioning document that Grafana loads on boot. Pass the UID of the VictoriaLogs datasource as configured in your Grafana install — the placeholder default (victorialogs) keeps the emitted YAML valid but will not load until substituted.

Each Sigma rule becomes one alert rule with a two-node data array:

• refId A runs the LogsQL stats query against the victoriametrics-logs-datasource plugin's /select/logsql/stats_query endpoint (Grafana ≥ 10.4 required).
• refId B is a server-side threshold expression that fires when A returns a non-zero count. condition: B is the rule's firing condition.

The Sigma → Grafana severity bucket is:

Backend options (-O <name>=<value>):

Deploying the rule provisioning file does not create the VictoriaLogs datasource itself — provision the datasource separately, then point the generated rules at it via grafana_datasource_uid. A complete deployment walkthrough (datasource provisioning + alert provisioning + alert-firing sanity check) lives at tests/e2e/grafana_alerting/README.md.

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.

Verifying releases

From v0.2.0 onward, every tagged release is signed with Sigstore via GitHub Actions OIDC. The signature bundles (*.sigstore.json) are attached to the corresponding GitHub release; the wheel and sdist on PyPI also carry a PEP 740 attestation (shown as a "Verified" badge on pypi.org).

Verify a downloaded artefact with sigstore-python:

gh release download v0.2.0 \
  --repo aris1009/pySigma-backend-victorialogs \
  --pattern '*.whl' --pattern '*.whl.sigstore.json'

pip install sigstore
sigstore verify github \
  --cert-identity "https://github.com/aris1009/pySigma-backend-victorialogs/.github/workflows/release-please.yml@refs/heads/main" \
  pysigma_backend_victorialogs-0.2.0-py3-none-any.whl

The cert-identity is the path of the workflow that produced the signature; because release-please publishes on push-to-main, the ref is refs/heads/main rather than the release tag.

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