sigma.grammar module

Sigma rule detection condition grammar parsing rules and classes. The classes defined here facilitate the abstract parsing of detection rules into Python-processable class structures. You should not need to interact directly with this module except when implementing serializers.

There are two main types of expressions defined here: core expressions and field comparisons. Core expressions are parsed from the Rule.detection.condition property and are things like the core logical expressions. While field comparisons are constructed from the detection matching identifiers and are things like field equality tests

class sigma.grammar.Base64FieldEquality(*, parent: Expression = None, field: str, value: Union[str, bytes])

Bases: sigma.grammar.FieldComparison

Test for field equality of base64 string

to_detection() → Tuple[str, List[Union[List, Dict]]]

Convert a not expression to a detection condition

value: Union[str, bytes]

class sigma.grammar.CoreExpression(*, parent: Expression = None, args: List[Union[sigma.grammar.Expression, str]])

Bases: sigma.grammar.Expression

Core expressions are the ones directly parsed from the condition grammar (as opposed to equality expressions parsed from detection tests).

args: List[Union[sigma.grammar.Expression, str]]

classmethod from_parsed(s: str, loc: int, tokens: pyparsing.results.ParseResults) → sigma.grammar.Expression

Convert the parsed expression into an expression instance

postprocess(rule: sigma.schema.RuleDetection, parent: Optional[Expression] = None) → Expression

class sigma.grammar.Expression(*, parent: Expression = None)

Bases: pydantic.main.BaseModel

Base class for all grammar expressions (and, or, not, identifier, selector)

operator: ClassVar[bool] = False

parent: Optional[sigma.grammar.Expression]

postprocess(rule: sigma.schema.RuleDetection, parent: Optional[Expression] = None) → Expression

to_detection() → Tuple[str, List[Union[List, Dict]]]

Convert an expression to a condition string and a dict of new detection selectors.

visit(callback: Callable[[sigma.grammar.Expression], sigma.grammar.Expression]) → sigma.grammar.Expression

Execute the given callback for each expression in the tree. The callback must return an expression to replace to visited expression (or the same reference to leave it unchanged).

class sigma.grammar.FieldComparison(*, parent: Expression = None, field: str, value: Any = None)

Bases: sigma.grammar.Expression

Base class for direct field comparisons

field: str

to_detection() → Tuple[str, List[Union[List, Dict]]]

Convert a not expression to a detection condition

to_field_with_modifiers() → str

value: Any

class sigma.grammar.FieldContains(*, parent: Expression = None, field: str, value: str)

Bases: sigma.grammar.FieldComparison

Test if a string is in the field somewhere

to_detection() → Tuple[str, List[Union[List, Dict]]]

Convert a not expression to a detection condition

to_field_with_modifiers() → str

value: str

class sigma.grammar.FieldEndsWith(*, parent: Expression = None, field: str, value: str)

Bases: sigma.grammar.FieldComparison

Test if a field ends with a token

to_detection() → Tuple[str, List[Union[List, Dict]]]

Convert a not expression to a detection condition

to_field_with_modifiers() → str

value: str

class sigma.grammar.FieldEquality(*, parent: Expression = None, field: str, value: Any = None)

Bases: sigma.grammar.FieldComparison

Test for field equality

field: str

parent: Optional[sigma.grammar.Expression]

to_detection() → Tuple[str, List[Union[List, Dict]]]

Convert a not expression to a detection condition

value: Any

class sigma.grammar.FieldLike(*, parent: Expression = None, field: str, value: Any = None)

Bases: sigma.grammar.FieldComparison

Test for field equality

field: str

parent: Optional[sigma.grammar.Expression]

postprocess(rule: sigma.schema.RuleDetection, parent: Optional[Expression] = None) → Expression

to_detection() → Tuple[str, List[Union[List, Dict]]]

Convert a not expression to a detection condition

value: Any

class sigma.grammar.FieldLookup(*, parent: Expression = None, field: str, value: List[Any])

Bases: sigma.grammar.FieldComparison

Check if the field is in a list of values with wildcard matching

value: List[Any]

class sigma.grammar.FieldLookupRegex(*, parent: Expression = None, field: str, value: List[str])

Bases: sigma.grammar.FieldLookup

Field lookup but with a regex modifier

to_field_with_modifiers() → str

value: List[str]

class sigma.grammar.FieldNotEmpty(*, parent: Expression = None, field: str, value: None = None)

Bases: sigma.grammar.FieldComparison

A field comparison such as ‘field is not null’

to_detection() → Tuple[str, List[Union[List, Dict]]]

Convert a not expression to a detection condition

value: None

class sigma.grammar.FieldRegex(*, parent: Expression = None, field: str, value: str)

Bases: sigma.grammar.FieldComparison

Compare a field with a regular expression

to_detection() → Tuple[str, List[Union[List, Dict]]]

Convert a not expression to a detection condition

to_field_with_modifiers() → str

value: str

class sigma.grammar.FieldStartsWith(*, parent: Expression = None, field: str, value: str)

Bases: sigma.grammar.FieldComparison

Test if a field starts with a token

to_detection() → Tuple[str, List[Union[List, Dict]]]

Convert a not expression to a detection condition

to_field_with_modifiers() → str

value: str

class sigma.grammar.Identifier(*, parent: Expression = None, args: List[Union[sigma.grammar.Expression, str]])

Bases: sigma.grammar.CoreExpression

Expression which identifies a specific detection condition

args: List[Union[sigma.grammar.Expression, str]]

property identifier: str

Shortcut for grabbing the identifier

parent: Optional[sigma.grammar.Expression]

postprocess(rule: sigma.schema.Rule, parent: Optional[sigma.grammar.Expression] = None) → sigma.grammar.Expression

Resolve the detection identifier

class sigma.grammar.KeywordSearch(*, parent: Expression = None, value: Any = None)

Bases: sigma.grammar.Expression

Search for a literal keyword/string instead of a direct comparison

to_detection() → Tuple[str, List[Union[List, Dict]]]

Convert a not expression to a detection condition

value: Any

class sigma.grammar.LogicalAnd(*, parent: Expression = None, args: List[Union[sigma.grammar.Expression, str]])

Bases: sigma.grammar.LogicalExpression

Logical And Expression

operator: ClassVar[bool] = True

postprocess(rule: sigma.schema.RuleDetection, parent: Optional[Expression] = None) → Expression

to_detection(group: bool = True) → Tuple[str, List[Union[List, Dict]]]

Convert a not expression to a detection condition

class sigma.grammar.LogicalExpression(*, parent: Expression = None, args: List[Union[sigma.grammar.Expression, str]])

Bases: sigma.grammar.CoreExpression

Logical expression

operator: ClassVar[bool] = True

postprocess(rule: sigma.schema.RuleDetection, parent: Optional[Expression] = None) → Expression

class sigma.grammar.LogicalNot(*, parent: Expression = None, args: List[Union[sigma.grammar.Expression, str]])

Bases: sigma.grammar.LogicalExpression

Logical not expression

operator: ClassVar[bool] = True

postprocess(detection: sigma.schema.RuleDetection, parent: Optional[Expression] = None) → Expression

Handle “not null” situations

to_detection() → Tuple[str, List[Union[List, Dict]]]

Convert a not expression to a detection condition

class sigma.grammar.LogicalOr(*, parent: Expression = None, args: List[Union[sigma.grammar.Expression, str]])

Bases: sigma.grammar.LogicalExpression

Logical Or expression

operator: ClassVar[bool] = True

postprocess(rule: sigma.schema.RuleDetection, parent: Optional[Expression] = None) → Expression

to_detection(group: bool = True) → Tuple[str, List[Union[List, Dict]]]

Convert a not expression to a detection condition

class sigma.grammar.Selector(*, parent: Expression = None, args: List[Union[sigma.grammar.Expression, str]])

Bases: sigma.grammar.CoreExpression

Selector expression which is converted to LogicalAnd or LogicalOr

args: List[Union[sigma.grammar.Expression, str]]

property condition: Type[sigma.grammar.CoreExpression]

parent: Optional[sigma.grammar.Expression]

property pattern: str

postprocess(rule: sigma.schema.Rule, parent: Optional[sigma.grammar.Expression] = None) → sigma.grammar.Expression

Collapse selector into either a logical OR or AND expression

sigma.grammar.base64_modifier(field: str, value: Any) → str

Base64 encode the field

sigma.grammar.base64offset_modifier(field: str, value: Any) → List[str]

Build the expression for matching a base64offset modified expression.

NOTE: I don’t fully understand what’s going on here, but I ripped it from pySigma… :eyes:

sigma.grammar.build_grammar_parser()

Build the pyparsing grammar parser for the condition field

sigma.grammar.build_key_value_expression(key: str, value: Union[list, str]) → sigma.grammar.Expression

Evaluate any modifiers in the given key and return a valid expression representing the key/value pair. These are taken directly from the detection definition.

sigma.grammar.utf16_modifier(field: str, value: Any) → bytes

sigma.grammar.utf16be_modifier(field: str, value: Any) → bytes

sigma.grammar.utf16le_modifier(field: str, value: Any, modifier: str = 'utf16le') → bytes

Transform the value into bytes

sigma.grammar.wide_modifier(field: str, value: Any) → bytes