sigma.serializer package

Serializers are used to convert a rule from the in-memory python representation to other arbitrary formats (such as Splunk queries or Elastic EQL queries). A serializer inherits from Serializer and defines the serialize() method which can return an arbitrary object which represents the serialized detection rule.

class sigma.serializer.CommonSerializerSchema(*, name: str, description: str = None, transforms: List[sigma.transform.Transformation.Schema] = None, base: str, logsource: sigma.serializer.LogSourceRules = LogSourceRules(defaultindex=[], merging='or', rules=[]))

Bases: pydantic.main.BaseModel

Base serializer schema which all schemas should inherit. Every serializer configuration is required to, at a minimum, conform to this schema. Custom serializers simply build off of this definition.

The base definition is one of the following

  • A built-in serializer name (as seen in sigma list serializer).

  • Path to a YAML serializer config

  • A fully qualified class name (e.g. package.module:ClassName).

Each transform definition must conform to the schema for the transform type, and at a minimum the Base Transformation Schema.

class Config

Bases: sigma.util.CopyableSchema

schema_extra = {'examples': [{'name': 'Serializer', 'description': 'A serializer', 'transforms': [], 'base': 'base_class', 'logsource': {'defaultindex': 'logs-*', 'merging': 'or', 'rules': [{'name': 'logsource match', 'product': 'windows', 'category': 'process_creation', 'index': 'logs-*'}]}}]}
base: str

The base type for this serialization. This is either the name of a builtin serializer class (e.g. TextQuerySerializer) or the name of another serialization schema file. If the latter case, the transforms from this serializer will be appended to the base, and any further configuration is ignored.

description: Optional[str]

Description of the schema

logsource: sigma.serializer.LogSourceRules

Rules to match log sources to indices

name: str

Arbitrary name for this serialization schema

transforms: Optional[List[sigma.transform.Transformation.Schema]]

List of transforms to be applied

class sigma.serializer.LogSourceMatch(*, name: str = None, product: str = None, service: str = None, category: str = None, conditions: sigma.schema.RuleDetectionFields = None, index: Optional[Union[str, List[str]]] = None)

Bases: pydantic.main.BaseModel

A single log source matching rule. The fields product, service and category are optional, but if specified must equal their respective fields in Rule.logsource.

The provided conditions are in the same format as a field selector within the Sigma rule itself, and can contain any of the common modifiers. The given conditions are joined with a logical AND expression to any matching rules.

The index can either be a string or list of strings and is used by some serializers to restrict the index on which the log search query is made.

The name field is not used internally, but is helpful to organize your serializer configuration if you have multiple different logsource matching sections.

class Config

Bases: sigma.util.CopyableSchema

schema_extra = {'examples': [{'name': 'logsource match', 'product': 'windows', 'category': 'process_creation', 'index': 'logs-*'}]}
category: Optional[str]

Category name match

compare(rule: sigma.schema.Rule) → bool

Test if Rule.logsource <sigma.schema.Rule.logsource matches this logsource definition.

Parameters

rule (Rule) – the rule to test

Return type

bool

Returns

True if the rule’s logsource details match this definition

conditions: Optional[sigma.schema.RuleDetectionFields]

List of field selectors to add to matching condition

index: Optional[Union[str, List[str]]]

One or more indices to search

name: Optional[str]

The matching rule name

product: Optional[str]

Product match

service: Optional[str]

Service name match

classmethod validate_detection(v)

Validate the schema for the

class sigma.serializer.LogSourceRules(*, defaultindex: Optional[Union[str, List[str]]] = [], merging: Union[Literal['or'], Literal['and']] = 'or', rules: List[sigma.serializer.LogSourceMatch] = [])

Bases: pydantic.main.BaseModel

This class represents the logsource field of a serializer definition, and controls the selection of indices based on matching rule logsource details to a list of logsource criteria.

A serializer can use the match_rule() method to identify matching logsource criteria defined by the serializer configuration and a list of matching indices to use when serializing the rule.

class Config

Bases: sigma.util.CopyableSchema

schema_extra = {'examples': [{'defaultindex': 'logs-*', 'merging': 'or', 'rules': [{'name': 'logsource match', 'product': 'windows', 'category': 'process_creation', 'index': 'logs-*'}]}]}
defaultindex: Optional[Union[str, List[str]]]

The default index if no log sources match or no indices defined

match_rule(rule: sigma.schema.Rule) → Tuple[List[str], sigma.schema.Rule]

Match the given rule to one or more logsource matches and return a list of indices and a (possibly modified) rule. This process is similar to a rule transformation, but matches rules to LogSourceMatches by inspecting the Rule.logsource field.

If no LogSourceMatch’s match this rule or no indices are defined in the match objects, the default index will be returned. The indices returned will always be a list regardless of the length. If no default index is defined, then the first item in the returned tuple could be an empty list.

The rule may have one or more conditional expressions joined to the original expression with a logical AND expression based on the conditions defined in one or more LogSourceMatch matches and the merging property.

Parameters

rule (Rule) – the rule to match against logsource matches

Return type

Tuple[List[str], Rule]

Returns

A tuple of (list_of_indices, modified_rule)

merging: Union[Literal['or'], Literal['and']]

how to merge multiple matching log sources

rules: List[sigma.serializer.LogSourceMatch]

List of log source matching rules

class sigma.serializer.Serializer(schema: sigma.serializer.CommonSerializerSchema)

Bases: abc.ABC

Base serialization class for Sigma rules. This class facilitates the transformation and serialization of sigma rules into a variety of arbitrary formats.

DEFAULT_FORMAT: ClassVar[Optional[str]] = None

Default format name when using dumps (used to highlight output)

Schema: ClassVar[Type[sigma.serializer.CommonSerializerSchema]]

The type for this serializers config schema

apply_rule_transform(rule: sigma.schema.Rule) → sigma.schema.Rule

Apply all rule and expression transformations, returning either a modified rule or a completely new rule depending on the transformations defined.

Parameters

rule (Rule) – the rule to transform

Return type

Rule

Returns

the transformed rule object (may be different from input)

abstract dumps(rule: List[sigma.schema.Rule], format: Optional[str] = None, pretty: bool = False, ignore_skip: bool = False) → str

Serialize the given rule(s) and return a string representation. Regardless of the number of rules passed, this method should always return a single string in the requested format. Formats are things like “raw”, “yaml”, or “json”. If the requested format is not supported, an UnsupportedSerializerFormat exception should be raised. If no format is given, this method should use the default format for the serializer.

Parameters

  • rule (List[Rule]) – list of rules to serialize and dump

  • format (str) – a format for dumping (e.g. “yaml” or “json”)

  • pretty (bool) – dump pretty-formatted output (default: false)

  • ignore_skip – If true, log and ignore SkipRule exceptions (default: false)

Return type

str

Returns

A string representation of the rule in the new target format

classmethod from_dict(definition: Dict[str, Any]) → sigma.serializer.Serializer

Construct a serializer from a dictionary definition conforming, at a minimum, to the CommonSerializerSchema schema. Other configuration may be necessary to construct the given base serializer class.

Parameters

definition (Dict[str, Any]) – a dictionary serializer configuration

Return type

Serializer

Returns

A new serializer instance of the requested type

classmethod from_yaml(path: Union[pathlib.Path, str, importlib.abc.Traversable]) → sigma.serializer.Serializer

Construct a serializer from a definition in a yaml file. This is the same as loading the YAML into a python dictionary and using Serializer.from_dict().

Parameters

path (Union[pathlib.Path, str, Traversable]) – a path-like object or string path to a YAML serializer definition

Return type

Serializer

Returns

A new serializer instance of the requested type

classmethod load(name: str, config: Optional[Union[Dict[str, Any], sigma.serializer.CommonSerializerSchema]] = None)

Load a serializer definition from any of:

  • Built-in definitions (see sigma list serializers)

  • A local file path

  • A fully qualified Python class path (e.g. package.module:ClassName)

If the provided name refers to a named serializer class or a fully qualified class name, then you should also provide the associated configuration dictionary to initialize the class. If no configuration is provided, an empty dictionary is passed to the classes initializer which could cause errors.

If the provided name refers to a serializer definition file (built-in or local), then the configuration argument is ignored.

Parameters

name (str) – name of the serializer to load

Return type

Serializer

Returns

A constructed serializer class from the given name/type

merge_config(config: sigma.serializer.CommonSerializerSchema)

Merge the given configuration into our current schema config

abstract serialize(rule: sigma.schema.Rule, transform: bool = True) → Any

Serialize the given sigma rule into a new format. The return value can be any python object which represents the equivalent rule in a new format.

Parameters

  • rule (Rule) – a rule to serialize

  • transform (bool) – whether to apply transformations (default: True, mainly used internally for inheritence)

Return type

Any

Returns

The serialized representation of the rule or a list of serialized representations.

transform(rule: sigma.schema.Rule) → Iterator[sigma.schema.Rule]
class sigma.serializer.TextQuerySerializer(schema: sigma.serializer.TextQuerySerializer.Schema)

Bases: sigma.serializer.Serializer

A basic serializer which only produces a static text query based on the condition and detection fields.

Parameters

schema (Schema) – A valid TextQuerySerializer configuration schema

class Schema(*, name: str, description: str = None, transforms: List[sigma.transform.Transformation.Schema] = None, base: str, logsource: sigma.serializer.LogSourceRules = LogSourceRules(defaultindex=[], merging='or', rules=[]), quote: str, escape: str, list_separator: str, or_format: str, and_format: str, not_format: str, grouping: str, escaped_characters: str, field_equality: str, field_like: str, field_match: str, field_regex: str, field_not_empty: str, keyword: str, field_startswith: str = None, field_endswith: str = None, field_contains: str = None, field_lookup: str = None, field_lookup_regex: str = None, bool_true: str = 'true', bool_false: str = 'false')

Bases: sigma.serializer.CommonSerializerSchema

Text Query configuration options which define how to combine the logical expressions into the correct query syntax for your detection engine.

and_format: str

A format string to construct an AND expression (e.g. “{} or {}”)

bool_false: str

Representation of a negative boolean value

bool_true: str

Representation of a positive boolean value

escape: str

The character used to escape the following character in a string

escaped_characters: str

Characters aside from the quote and escape character that require escaping

field_contains: Optional[str]

A format string to test if a field contains another string

field_endswith: Optional[str]

A format string to test if a field ends with a string

field_equality: str

A format string to test field equality (e.g. “{} == {}”)

field_like: str

Format for matching a field to a single pattern (e.g. “{} like~ {}”)

field_lookup: Optional[str]

Format for matching a field to a list of patterns (e.g. “{} like~ {}”)

field_lookup_regex: Optional[str]

Format for matching a field to a list of regex patterns (e.g. “{} regex {}”)

field_match: str

A format string to test a field with a globbing pattern (e.g. “{}: {}”)

field_not_empty: str

Test if a field exists

field_regex: str

A format string to test if a field matches a regex (e.g. “{} match {}”)

field_startswith: Optional[str]

A format string to test if a field starts with a string

grouping: str

A format string to construct a grouping (e.g. “({})”)

keyword: str

A format string to match a keyword across all fields (e.g. “{}”)

list_separator: str

The string used to separate list items

not_format: str

A format string to construct a NOT expression (e.g. “not {}”)

or_format: str

A format string to construct an OR expression (e.g. “{} or {}”)

quote: str

The character used for literal escapes in strings

dumps(rule: List[sigma.schema.Rule], format: Optional[str] = None, pretty: bool = False, ignore_skip: bool = True) → str

The rule(s) to a string. In the case of a TextQuerySerializer, this is the same as dumping the rule(s) directly, with newlines separating

serialize(rule: sigma.schema.Rule, transform: bool = True) → str

Serialize the rule to a single text query

Parameters

  • rule (Rule) – a rule to be serialized

  • transform (bool) – whether to apply transformations (default: True)

Return type

str

Returns

the serialized rule

transforms: List[sigma.transform.Transformation]
sigma.serializer.get_builtin_serializers() → Generator[Tuple[str, str], None, None]

Iterate over built-in serializers. This method is a generator which yields a tuple of [name, description] for all built-in serializers.

sigma.serializer.get_serializer_class(name: str) → Type[sigma.serializer.Serializer]

Retrieve the class backing the given serializer