Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

fix(api): the Sigma matcher could not fire, and said nothing (#982)

Beenu Arorac8b9d6700a0f
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8711aec74..336f02f1c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -876,6 +876,18 @@ jobs:
runs-on: ubuntu-latest
needs: python-lint
env:
+ # `API_DEPS` is a folded scalar: every line below joins into one
+ # command, so a `#` inside it comments out the remainder of the
+ # install list. Keep prose out of the value.
+ #
+ # pysigma and pysigma-backend-opensearch are here because the Sigma
+ # path this job tests imports them. Without them
+ # `rule_engine._run_sigma` took its ImportError branch, so every Sigma
+ # test graded the reduced built-in evaluator, while the published image
+ # installs pysigma from the lockfile and ran the real backend. CI and
+ # production evaluated Sigma rules with different engines, and the one
+ # CI never ran was the broken one. Ranges mirror
+ # services/api/pyproject.toml.
API_DEPS: >-
"fastapi>=0.117,<0.142" "pydantic[email]" pydantic-settings "sqlalchemy[asyncio]" asyncpg
structlog "PyJWT>=2.8,<3" "cryptography>=46,<51" "passlib[bcrypt]" tenacity pyyaml
@@ -886,6 +898,7 @@ jobs:
neo4j redis celery httpx aiofiles email-validator "PyJWT>=2.8,<3"
"sqlglot>=30,<31" aiosqlite
"croniter>=2.0,<7.0"
+ "pysigma>=0.11,<0.12" "pysigma-backend-opensearch>=1.0,<2.0"
pytest pytest-asyncio
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
diff --git a/services/api/app/services/lucene_eval.py b/services/api/app/services/lucene_eval.py
new file mode 100644
index 000000000..00700ab6f
--- /dev/null
+++ b/services/api/app/services/lucene_eval.py
@@ -0,0 +1,330 @@
+"""Evaluate a Lucene query against one in-memory event, with real boolean semantics.
+
+Why this exists
+---------------
+``rule_engine._run_sigma`` converts a Sigma rule with pySigma's OpenSearch
+backend and then has to decide, in this process, whether an event matches the
+resulting query. It used to do that with::
+
+ return query.lower() in " ".join(f"{k}:{v}" for k, v in flat.items()).lower()
+
+A Lucene boolean expression is never a contiguous substring of a
+``key:value key:value`` join, so the moment a rule had two clauses —
+``Image:*\\powershell.exe AND CommandLine:*Mimikatz*``, which is what the
+backend emits for a two-field ``selection`` — it matched **nothing**, and
+returned ``False`` without an error. A rule that cannot fire and a rule that
+found nothing are indistinguishable to every caller: the backtest reported
+``would_fire: 0`` with a straight face, the candidate-rule eval gate failed
+every Sigma proposal on its own positive fixtures, and scheduled Sigma hunts
+returned zero hits.
+
+Substring containment cannot represent a boolean. Nothing short of parsing
+the query fixes it, so this module parses the query.
+
+Scope
+-----
+The subset pySigma's OpenSearch backend actually emits, which is what this
+has to evaluate correctly:
+
+=============================== ==========================================
+``EventID:4625`` term equality
+``Image:*\\powershell.exe`` wildcards (``*`` any run, ``?`` one char)
+``TargetUserName:(a OR b)`` grouped alternatives on one field
+``CommandLine:/foo.*bar/`` regular expression
+``NOT _exists_:User`` field-absence, from a Sigma ``null``
+``*whoami*`` a bare term, from Sigma keywords
+``A AND B``, ``A OR B``, ``(…)`` boolean composition
+``Name:Remote\\ Desktop`` backslash escaping of any metacharacter
+=============================== ==========================================
+
+Matching is case-insensitive, which is Sigma's default.
+
+Anything outside that subset raises :class:`LuceneQueryError` rather than
+evaluating to ``False``. That direction is the whole point: a query this
+module cannot read must surface as an error the caller reports, never as a
+quiet "no match" that reads exactly like a clean event.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = ["LuceneQueryError", "lucene_matches", "parse_lucene"]
+
+
+class LuceneQueryError(ValueError):
+ """The query uses something this evaluator cannot faithfully represent."""
+
+
+# ─── Tokeniser ───────────────────────────────────────────────────────────────
+
+# A run of query text that is one token: either a bare word (with backslash
+# escapes, so `Remote\ Desktop` stays a single token) or a /regex/ literal.
+_TOKEN_RE = re.compile(
+ r"""
+ /(?P<regex>(?:\\.|[^/\\])*)/ # /.../ with escapes
+ | (?P<term>(?:\\.|[^\s():])+) # bare term; ( ) : and space end it unless escaped
+ """,
+ re.VERBOSE,
+)
+
+_KEYWORDS = {"AND", "OR", "NOT", "&&", "||", "!"}
+
+
+@dataclass(frozen=True, slots=True)
+class _Token:
+ kind: str # "lparen" | "rparen" | "colon" | "kw" | "term" | "regex"
+ value: str
+
+
+def _tokenise(query: str) -> list[_Token]:
+ tokens: list[_Token] = []
+ i = 0
+ n = len(query)
+ while i < n:
+ ch = query[i]
+ if ch.isspace():
+ i += 1
+ continue
+ if ch == "(":
+ tokens.append(_Token("lparen", "("))
+ i += 1
+ continue
+ if ch == ")":
+ tokens.append(_Token("rparen", ")"))
+ i += 1
+ continue
+ if ch == ":":
+ tokens.append(_Token("colon", ":"))
+ i += 1
+ continue
+ match = _TOKEN_RE.match(query, i)
+ if match is None:
+ raise LuceneQueryError(f"cannot tokenise at offset {i}: {query[i : i + 30]!r}")
+ if match.lastgroup == "regex" or match.group("regex") is not None:
+ tokens.append(_Token("regex", match.group("regex")))
+ else:
+ text = match.group("term")
+ tokens.append(_Token("kw", text.upper()) if text.upper() in _KEYWORDS else _Token("term", text))
+ i = match.end()
+ return tokens
+
+
+# ─── AST ─────────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class _Term:
+ field: str | None # None => match against every field's value
+ pattern: str
+ is_regex: bool
+
+
+@dataclass(frozen=True, slots=True)
+class _Exists:
+ field: str
+
+
+@dataclass(frozen=True, slots=True)
+class _Not:
+ operand: Any
+
+
+@dataclass(frozen=True, slots=True)
+class _BoolOp:
+ op: str # "AND" | "OR"
+ operands: tuple[Any, ...]
+
+
+# ─── Parser ──────────────────────────────────────────────────────────────────
+
+
+class _Parser:
+ def __init__(self, tokens: list[_Token]) -> None:
+ self._tokens = tokens
+ self._pos = 0
+
+ def _peek(self, offset: int = 0) -> _Token | None:
+ index = self._pos + offset
+ return self._tokens[index] if index < len(self._tokens) else None
+
+ def _take(self) -> _Token:
+ token = self._peek()
+ if token is None:
+ raise LuceneQueryError("query ended where a term was expected")
+ self._pos += 1
+ return token
+
+ def parse(self) -> Any:
+ if not self._tokens:
+ raise LuceneQueryError("empty query")
+ node = self._or()
+ if self._peek() is not None:
+ raise LuceneQueryError(f"unconsumed input at token {self._pos}: {self._tokens[self._pos].value!r}")
+ return node
+
+ def _or(self) -> Any:
+ operands = [self._and()]
+ while (token := self._peek()) is not None and token.kind == "kw" and token.value in ("OR", "||"):
+ self._take()
+ operands.append(self._and())
+ return operands[0] if len(operands) == 1 else _BoolOp("OR", tuple(operands))
+
+ def _and(self) -> Any:
+ operands = [self._not()]
+ while (token := self._peek()) is not None:
+ if token.kind == "kw" and token.value in ("AND", "&&"):
+ self._take()
+ operands.append(self._not())
+ continue
+ # Lucene's implicit operator. The backend always emits an explicit
+ # one, so an adjacency here means the query is not the shape this
+ # evaluator was written against: refuse rather than guess whether
+ # the default is AND or OR.
+ if token.kind in ("term", "regex", "lparen"):
+ raise LuceneQueryError(f"implicit operator before {token.value!r}; only explicit AND/OR are supported")
+ break
+ return operands[0] if len(operands) == 1 else _BoolOp("AND", tuple(operands))
+
+ def _not(self) -> Any:
+ token = self._peek()
+ if token is not None and token.kind == "kw" and token.value in ("NOT", "!"):
+ self._take()
+ return _Not(self._not())
+ return self._primary()
+
+ def _primary(self) -> Any:
+ token = self._take()
+ if token.kind == "lparen":
+ node = self._or()
+ closing = self._take()
+ if closing.kind != "rparen":
+ raise LuceneQueryError(f"expected ')' , got {closing.value!r}")
+ return node
+ if token.kind == "regex":
+ return _Term(None, token.value, is_regex=True)
+ if token.kind != "term":
+ raise LuceneQueryError(f"expected a term, got {token.value!r}")
+
+ following = self._peek()
+ if following is None or following.kind != "colon":
+ return _Term(None, token.value, is_regex=False)
+
+ self._take() # consume ':'
+ field = token.value
+ value = self._take()
+ if value.kind == "regex":
+ return _Term(field, value.value, is_regex=True)
+ if value.kind == "lparen":
+ # `field:(a OR b)` — the alternatives all bind to this field.
+ group = self._field_group(field)
+ closing = self._take()
+ if closing.kind != "rparen":
+ raise LuceneQueryError(f"expected ')' closing {field}:(...), got {closing.value!r}")
+ return group
+ if value.kind != "term":
+ raise LuceneQueryError(f"expected a value after {field}:, got {value.value!r}")
+ if field == "_exists_":
+ return _Exists(_unescape(value.value))
+ return _Term(field, value.value, is_regex=False)
+
+ def _field_group(self, field: str) -> Any:
+ operands: list[Any] = []
+ op = "OR"
+ while True:
+ token = self._take()
+ if token.kind == "regex":
+ operands.append(_Term(field, token.value, is_regex=True))
+ elif token.kind == "term":
+ operands.append(_Term(field, token.value, is_regex=False))
+ else:
+ raise LuceneQueryError(f"expected a value inside {field}:(...), got {token.value!r}")
+ nxt = self._peek()
+ if nxt is not None and nxt.kind == "kw" and nxt.value in ("OR", "AND", "||", "&&"):
+ self._take()
+ op = "AND" if nxt.value in ("AND", "&&") else "OR"
+ continue
+ break
+ return operands[0] if len(operands) == 1 else _BoolOp(op, tuple(operands))
+
+
+def parse_lucene(query: str) -> Any:
+ """Parse ``query`` into an evaluable tree, or raise :class:`LuceneQueryError`."""
+ return _Parser(_tokenise(query)).parse()
+
+
+# ─── Evaluation ──────────────────────────────────────────────────────────────
+
+
+def _unescape(text: str) -> str:
+ return re.sub(r"\\(.)", r"\1", text)
+
+
+def _to_matcher(pattern: str, *, is_regex: bool) -> re.Pattern[str]:
+ if is_regex:
+ try:
+ return re.compile(pattern, re.IGNORECASE)
+ except re.error as exc:
+ raise LuceneQueryError(f"bad regular expression {pattern!r}: {exc}") from exc
+ # Build the expression from escaped literals so a value carrying regex
+ # metacharacters -- a Windows path, a command line -- cannot become one.
+ # Only `*` and `?` survive as wildcards, which is what Lucene means.
+ out: list[str] = []
+ i = 0
+ while i < len(pattern):
+ ch = pattern[i]
+ if ch == "\\" and i + 1 < len(pattern):
+ out.append(re.escape(pattern[i + 1]))
+ i += 2
+ continue
+ if ch == "*":
+ out.append(".*")
+ elif ch == "?":
+ out.append(".")
+ else:
+ out.append(re.escape(ch))
+ i += 1
+ return re.compile(f"^{''.join(out)}$", re.IGNORECASE | re.DOTALL)
+
+
+def _values_for(event: dict[str, Any], field: str) -> list[Any]:
+ key = _unescape(field).lower()
+ if key in event:
+ value = event[key]
+ return list(value) if isinstance(value, list | tuple) else [value]
+ return []
+
+
+def _evaluate(node: Any, event: dict[str, Any]) -> bool:
+ if isinstance(node, _BoolOp):
+ results = (_evaluate(operand, event) for operand in node.operands)
+ return all(results) if node.op == "AND" else any(results)
+ if isinstance(node, _Not):
+ return not _evaluate(node.operand, event)
+ if isinstance(node, _Exists):
+ return event.get(node.field.lower()) is not None
+ if isinstance(node, _Term):
+ matcher = _to_matcher(node.pattern, is_regex=node.is_regex)
+ check = matcher.search if node.is_regex else matcher.match
+ if node.field is None:
+ # A bare term. Sigma keywords search the whole record, so this
+ # matches anywhere in any value rather than the whole of one.
+ loose = matcher if node.is_regex else _to_matcher(f"*{node.pattern}*", is_regex=False)
+ return any(loose.match(str(value)) for value in event.values() if value is not None)
+ return any(check(str(value)) for value in _values_for(event, node.field) if value is not None)
+ raise LuceneQueryError(f"unsupported node {node!r}")
+
+
+def lucene_matches(query: str, flat_event: dict[str, Any]) -> bool:
+ """Whether ``flat_event`` satisfies ``query``.
+
+ ``flat_event`` is a flattened, lower-cased-key mapping as produced by
+ ``rule_engine._flatten_dict``.
+
+ Raises:
+ LuceneQueryError: the query is outside the supported subset. Callers
+ must surface this rather than treating it as a non-match.
+ """
+ return _evaluate(parse_lucene(query), flat_event)
diff --git a/services/api/app/services/rule_engine.py b/services/api/app/services/rule_engine.py
index 191dfee3c..fae83abd3 100644
--- a/services/api/app/services/rule_engine.py
+++ b/services/api/app/services/rule_engine.py
@@ -15,6 +15,8 @@ from dataclasses import dataclass, field
from enum import Enum
from typing import Any
+from app.services.lucene_eval import LuceneQueryError, lucene_matches
+
logger = logging.getLogger(__name__)
@@ -61,6 +63,17 @@ class HuntResult:
# ─── Sigma Runner ─────────────────────────────────────────────────────────────
+#: Reported instead of ``None`` when pySigma is missing and the reduced
+#: evaluator answered instead. Callers show ``error`` to an operator, so this
+#: is the difference between "this rule found nothing" and "a different, less
+#: capable evaluator found nothing".
+SIGMA_DEGRADED = (
+ "pySigma is not installed; this rule was evaluated by the reduced built-in "
+ "evaluator, which ignores Sigma field modifiers. Install pysigma and "
+ "pysigma-backend-opensearch for full semantics."
+)
+
+
def _run_sigma(rule_body: str, events: list[dict[str, Any]]) -> tuple[list[dict], str | None]:
"""
Execute a Sigma rule against a list of events.
@@ -70,7 +83,17 @@ def _run_sigma(rule_body: str, events: list[dict[str, Any]]) -> tuple[list[dict]
try:
from sigma.backends.opensearch import OpensearchLuceneBackend
from sigma.rule import SigmaRule
+ except ImportError:
+ # Not a non-event. The reduced evaluator below reads a Sigma
+ # `detection` block as plain substring containment and ignores every
+ # field modifier, so its answer is not the answer the real backend
+ # would give. Returning `None` here reported that difference as
+ # nothing at all, which is how a deployment can silently evaluate
+ # every Sigma rule with the wrong engine.
+ logger.warning("pySigma unavailable; Sigma rules are being evaluated by the reduced built-in evaluator")
+ return _sigma_fallback(rule_body, events), SIGMA_DEGRADED
+ try:
sigma_rule = SigmaRule.from_yaml(rule_body)
backend = OpensearchLuceneBackend()
queries = backend.convert_rule(sigma_rule)
@@ -79,14 +102,10 @@ def _run_sigma(rule_body: str, events: list[dict[str, Any]]) -> tuple[list[dict]
matched = []
for event in events:
for query in queries:
- if _lucene_match(query, event):
+ if _lucene_match(str(query), event):
matched.append(event)
break
return matched, None
-
- except ImportError:
- # pySigma not available – use simple YAML condition evaluator
- return _sigma_fallback(rule_body, events), None
except Exception as exc:
logger.warning("Sigma parse error: %s", exc)
return _sigma_fallback(rule_body, events), str(exc)
@@ -400,10 +419,32 @@ def _run_eql(rule_body: str, events: list[dict[str, Any]]) -> tuple[list[dict],
def _lucene_match(query: str, event: dict[str, Any]) -> bool:
- """Simple Lucene query evaluator for field:value pairs."""
- flat = _flatten_dict(event)
- flat_str = " ".join(f"{k}:{v}" for k, v in flat.items()).lower()
- return query.lower() in flat_str
+ """Whether ``event`` satisfies ``query``, with real boolean semantics.
+
+ This was ``query.lower() in " ".join(f"{k}:{v}" ...)``. A Lucene boolean
+ expression is never a contiguous substring of a ``key:value`` join, so
+ every multi-clause query — which is what pySigma emits for any rule with
+ two fields — matched nothing and reported no error. See
+ :mod:`app.services.lucene_eval`.
+ """
+ return lucene_matches(query, _flatten_dict(event))
+
+
+def _run_lucene(rule_body: str, events: list[dict[str, Any]]) -> tuple[list[dict], str | None]:
+ """Execute a rule authored directly in Lucene.
+
+ This used to be routed to ``_run_kql``, whose matcher reads the first
+ ``field:value`` it can regex out of the query and otherwise falls back to
+ ``query.lower() in flat_str``. Both readings drop every boolean operator,
+ so a two-clause Lucene rule was answered by substring containment.
+ """
+ try:
+ matched = [event for event in events if lucene_matches(rule_body.strip(), _flatten_dict(event))]
+ except LuceneQueryError as exc:
+ # An unreadable query is not an absence of matches, and saying so is
+ # the only thing that distinguishes the two for the caller.
+ return [], f"unsupported Lucene query: {exc}"
+ return matched, None
def _flatten_dict(d: dict[str, Any], prefix: str = "") -> dict[str, Any]:
@@ -429,7 +470,7 @@ def _rule_runners():
"yara": _run_yara,
"kql": _run_kql,
"eql": _run_eql,
- "lucene": lambda body, evts: (_run_kql(body, evts)[0], None),
+ "lucene": _run_lucene,
"regex": _run_regex,
}
diff --git a/services/api/tests/test_sigma_backend_matching.py b/services/api/tests/test_sigma_backend_matching.py
new file mode 100644
index 000000000..018a01d16
--- /dev/null
+++ b/services/api/tests/test_sigma_backend_matching.py
@@ -0,0 +1,248 @@
+"""The Sigma path must fire on a true positive, and must say when it cannot.
+
+Two defects sat here, and between them no Sigma rule evaluated by this engine
+could ever have matched an event:
+
+1. ``_lucene_match`` was ``query.lower() in " ".join(f"{k}:{v}" ...)``. A
+ Lucene boolean expression is never a contiguous substring of a
+ ``key:value`` join, so ``Image:*\\powershell.exe AND CommandLine:*Mimikatz*``
+ — what pySigma's OpenSearch backend emits for a two-field ``selection`` —
+ matched nothing and returned ``False`` with no error.
+
+2. ``_run_sigma`` caught ``ImportError`` and returned the reduced built-in
+ evaluator's answer with ``error=None``. So a deployment without pySigma
+ silently ran a different, weaker evaluator and nothing anywhere said so.
+
+The two interact badly. ``.github/workflows/ci.yml`` did not install pysigma,
+so every Sigma test in CI exercised the fallback, while the Docker image
+installs it from the lockfile and ran the broken real path. CI and production
+evaluated Sigma rules with different engines, and the one CI never ran was
+the broken one. The workflow now installs pysigma, and
+``test_ci_installs_the_backend_it_claims_to_test`` fails if that is undone —
+otherwise the pySigma tests below would skip in CI and report green.
+
+Three callers depended on the answer: ``POST /rules/{id}/backtest`` (which
+exists to report an honest ``would_fire``), ``detection_eval`` (the gate a
+candidate rule has to pass on its own positive fixtures), and the scheduled
+hunt worker.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+import yaml
+from app.services.detection_eval import evaluate_candidate_rule
+from app.services.lucene_eval import LuceneQueryError, lucene_matches
+from app.services.rule_engine import SIGMA_DEGRADED, _run_sigma, execute_rule
+
+pysigma = pytest.importorskip("sigma.backends.opensearch", reason="pysigma is required for the real Sigma backend path")
+
+TWO_CLAUSE_RULE = """
+title: PowerShell running Mimikatz
+id: 11111111-2222-3333-4444-555555555555
+status: test
+logsource:
+ category: process_creation
+ product: windows
+detection:
+ selection:
+ Image|endswith: '\\powershell.exe'
+ CommandLine|contains: 'Invoke-Mimikatz'
+ condition: selection
+level: high
+"""
+
+TRUE_POSITIVE = {
+ "Image": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
+ "CommandLine": "powershell.exe -enc Invoke-Mimikatz -DumpCreds",
+}
+# Satisfies exactly one of the two AND-ed clauses. A matcher that has lost the
+# boolean either fires on this or fires on nothing; both are wrong.
+HALF_MATCH = {
+ "Image": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
+ "CommandLine": "Get-ChildItem -Recurse",
+}
+TRUE_NEGATIVE = {"Image": "C:\\Windows\\System32\\cmd.exe", "CommandLine": "dir"}
+
+
+class TestTheRealBackendFires:
+ def test_a_two_clause_sigma_rule_fires_on_its_true_positive(self) -> None:
+ matched, error = _run_sigma(TWO_CLAUSE_RULE, [TRUE_POSITIVE])
+ assert error is None, error
+ assert matched == [TRUE_POSITIVE], "a rule that cannot fire on its own true positive can never fire at all"
+
+ def test_it_stays_silent_when_only_one_clause_holds(self) -> None:
+ matched, error = _run_sigma(TWO_CLAUSE_RULE, [HALF_MATCH])
+ assert error is None, error
+ assert matched == [], "AND must require both clauses"
+
+ def test_it_stays_silent_on_an_unrelated_event(self) -> None:
+ matched, error = _run_sigma(TWO_CLAUSE_RULE, [TRUE_NEGATIVE])
+ assert error is None, error
+ assert matched == []
+
+ def test_the_candidate_rule_gate_can_pass_a_sigma_rule(self) -> None:
+ """``detection_eval`` is the promote-gate for a proposed detection.
+
+ With the matcher unable to fire, every Sigma candidate failed on its
+ own positive fixture, so the gate rejected correct rules for a reason
+ that had nothing to do with them.
+ """
+ result = evaluate_candidate_rule(
+ rule_language="sigma",
+ rule_body=TWO_CLAUSE_RULE,
+ positive_fixtures=[TRUE_POSITIVE],
+ negative_fixtures=[HALF_MATCH, TRUE_NEGATIVE],
+ )
+ assert result.passed, result.reason
+ assert (result.positives_fired, result.negatives_fired) == (1, 0)
+
+ def test_execute_rule_reports_the_match_through_the_public_surface(self) -> None:
+ match = execute_rule(
+ rule_id="r1",
+ rule_name="PowerShell running Mimikatz",
+ rule_language="sigma",
+ rule_body=TWO_CLAUSE_RULE,
+ severity="high",
+ events=[TRUE_POSITIVE, TRUE_NEGATIVE],
+ )
+ assert match.matched is True
+ assert match.error is None
+
+
+class TestTheLuceneEvaluator:
+ @pytest.mark.parametrize(
+ ("query", "event", "expected"),
+ [
+ ("EventID:4625", {"eventid": 4625}, True),
+ ("EventID:4625", {"eventid": 4624}, False),
+ ("a:1 AND b:2", {"a": 1, "b": 2}, True),
+ ("a:1 AND b:2", {"a": 1, "b": 3}, False),
+ ("a:1 OR b:2", {"a": 9, "b": 2}, True),
+ ("a:1 OR b:2", {"a": 9, "b": 9}, False),
+ ("NOT a:1", {"a": 2}, True),
+ ("NOT a:1", {"a": 1}, False),
+ ("(a:1 OR a:2) AND b:3", {"a": 2, "b": 3}, True),
+ ("(a:1 OR a:2) AND b:3", {"a": 3, "b": 3}, False),
+ ("TargetUserName:(admin OR root)", {"targetusername": "root"}, True),
+ ("TargetUserName:(admin OR root)", {"targetusername": "guest"}, False),
+ ("Image:*\\\\net.exe", {"image": "C:\\Windows\\System32\\net.exe"}, True),
+ ("Image:*\\\\net.exe", {"image": "C:\\Windows\\System32\\cmd.exe"}, False),
+ ("ParentImage:C\\:\\\\Windows*", {"parentimage": "C:\\Windows\\explorer.exe"}, True),
+ ("CommandLine:/inv.*mimi/", {"commandline": "Invoke-Mimikatz"}, True),
+ ("CommandLine:/inv.*mimi/", {"commandline": "Get-Process"}, False),
+ ("NOT _exists_:User", {"other": 1}, True),
+ ("NOT _exists_:User", {"user": "alice"}, False),
+ ("*whoami*", {"cmd": "c:\\tools\\whoami.exe -all"}, True),
+ ("*whoami*", {"cmd": "ipconfig"}, False),
+ ("ServiceName:Remote\\ Desktop\\ Services", {"servicename": "Remote Desktop Services"}, True),
+ # A value carrying regex metacharacters must be a literal, not a pattern.
+ ("path:a.b", {"path": "axb"}, False),
+ ("path:a.b", {"path": "a.b"}, True),
+ ],
+ )
+ def test_boolean_and_wildcard_semantics(self, query: str, event: dict[str, Any], expected: bool) -> None:
+ assert lucene_matches(query, event) is expected
+
+ def test_a_query_outside_the_supported_subset_raises_rather_than_returning_false(self) -> None:
+ """Refusing is the property. A `False` here reads exactly like a clean event."""
+ with pytest.raises(LuceneQueryError):
+ lucene_matches("a:1 b:2", {"a": 1, "b": 2}) # implicit operator
+ with pytest.raises(LuceneQueryError):
+ lucene_matches("(a:1", {"a": 1})
+ with pytest.raises(LuceneQueryError):
+ lucene_matches("", {})
+
+ def test_the_substring_matcher_this_replaced_could_not_have_passed(self) -> None:
+ """Pin the defect so the old implementation cannot quietly return.
+
+ This is the exact expression that shipped. It is kept here rather than
+ described, because the claim "substring containment cannot represent a
+ boolean" is worth demonstrating against the same inputs the real
+ matcher is graded on above.
+ """
+ backend = pysigma.OpensearchLuceneBackend()
+ from sigma.rule import SigmaRule
+
+ queries = [str(q) for q in backend.convert_rule(SigmaRule.from_yaml(TWO_CLAUSE_RULE))]
+ flat = {k.lower(): v for k, v in TRUE_POSITIVE.items()}
+ joined = " ".join(f"{k}:{v}" for k, v in flat.items()).lower()
+
+ assert not any(q.lower() in joined for q in queries), "premise changed: the old matcher would have worked"
+ assert any(lucene_matches(q, flat) for q in queries), "the replacement must fire where the old one could not"
+
+
+class TestRulesAuthoredDirectlyInLucene:
+ """`rule_language: lucene` was routed to the KQL matcher, which drops booleans.
+
+ `_kql_match` regexes out the *first* `field:value` it can find and
+ otherwise falls back to `query.lower() in flat_str`. So a two-clause
+ Lucene rule fired whenever its first clause held, whatever the second
+ one said — which passes a naive true-positive test and is wrong on
+ exactly the events a second clause exists to exclude.
+ """
+
+ QUERY = "Image:*powershell.exe AND CommandLine:*Mimikatz*"
+
+ def _matched(self, event: dict[str, Any]) -> bool:
+ return execute_rule(
+ rule_id="r2",
+ rule_name="two clause lucene",
+ rule_language="lucene",
+ rule_body=self.QUERY,
+ severity="high",
+ events=[event],
+ ).matched
+
+ def test_it_fires_when_both_clauses_hold(self) -> None:
+ assert self._matched(TRUE_POSITIVE) is True
+
+ def test_it_stays_silent_when_only_the_first_clause_holds(self) -> None:
+ assert self._matched(HALF_MATCH) is False, "the second clause of an AND was being ignored"
+
+ def test_an_unreadable_query_is_an_error_not_an_absence_of_matches(self) -> None:
+ match = execute_rule(
+ rule_id="r3",
+ rule_name="malformed",
+ rule_language="lucene",
+ rule_body="(Image:*powershell.exe",
+ severity="high",
+ events=[TRUE_POSITIVE],
+ )
+ assert match.matched is False
+ assert match.error and "unsupported Lucene query" in match.error
+
+
+class TestTheFallbackIsNotSilent:
+ def test_a_missing_backend_is_reported_rather_than_returned_as_no_error(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """Without this, a deployment lacking pySigma runs a weaker evaluator invisibly."""
+ monkeypatch.setitem(sys.modules, "sigma.backends.opensearch", None)
+ matched, error = _run_sigma(TWO_CLAUSE_RULE, [TRUE_POSITIVE])
+ assert error == SIGMA_DEGRADED, f"the degraded path must name itself, got {error!r}"
+ assert isinstance(matched, list)
+
+
+def test_ci_installs_the_backend_it_claims_to_test() -> None:
+ """The pySigma tests above `importorskip`. A skip in CI would be a green lie.
+
+ CI installed the API's dependencies from a hand-curated pip list that did
+ not name pysigma, so the real backend path had never once run in CI while
+ the published image installed it from the lockfile and ran it. Assert the
+ workflow installs it, so the only place these tests can skip is a local
+ checkout that chose not to.
+ """
+ root = Path(__file__).resolve().parents[3]
+ workflow = yaml.safe_load((root / ".github" / "workflows" / "ci.yml").read_text())
+ deps = str(workflow["jobs"]["python-test"]["env"]["API_DEPS"])
+ assert "pysigma" in deps, "ci.yml must install pysigma or the Sigma backend tests silently skip"
+ assert "pysigma-backend-opensearch" in deps, "the OpenSearch backend is what rule_engine imports"
+ # `API_DEPS` is a folded scalar, so every line joins into one shell word
+ # list and a `#` anywhere inside comments out the remainder. A rationale
+ # written between two packages silently uninstalled everything after it,
+ # pytest included, and the job failed with "No module named pytest".
+ assert "#" not in deps, f"a comment inside the folded scalar truncates the install list: {deps}"
+ assert deps.split()[-1] == "pytest-asyncio", "the tail of the install list was swallowed"