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.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
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.ymlindex 8711aec74..336f02f1c 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -876,6 +876,18 @@ jobs:runs-on: ubuntu-latestneeds: python-lintenv:+ # `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]" asyncpgstructlog "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-asynciosteps:- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7diff --git a/services/api/app/services/lucene_eval.py b/services/api/app/services/lucene_eval.pynew file mode 100644index 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.pyindex 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, fieldfrom enum import Enumfrom 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 OpensearchLuceneBackendfrom 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)breakreturn matched, None-- except ImportError:- # pySigma not available – use simple YAML condition evaluator- return _sigma_fallback(rule_body, events), Noneexcept 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, Nonedef _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.pynew file mode 100644index 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"