sigma.transform package¶

Sigma rule transformation classes.

Sigma transformations can operator on either rules as a whole and/or on individual expressions within the evaluated detection condition. The most commonly used transform is the FieldTransform which is used to replace built-in field names with custom field names.

Example Custom Transformation Class¶

class CustomTransform(Transformation):

    def __init__(self, config: Dict[str, Any]):
        # Validate and/or use the configuration if needed
        super().__init__(config)

    def transform_rule(self, rule: Rule) -> Rule:
        # Modify the rule
        rule.title += " a modified title!"

    def transform_expression(self, expression: Expression) -> Expression:
        # Modify an expression
        return expression

Transformation Schema¶

Transformations can also be loaded from a serialized schema, normally within a serializer configuration. A transformation schema has two fields: type and config. The transformation type can either be one of the built-in transformation names or a fully-qualified python class path formatted as package.module:ClassName.

Example YAML transformation definition¶

transformations:
    - type: field
      config:
        CommandLine: process.command_line
        Image: process.executable
        ParentImage: process.parent.executable

class sigma.transform.AddTags(schema: sigma.transform.Transformation.Schema)¶

Bases: sigma.transform.Transformation

Add extra tags to a sigma rule during serialization.

class Schema(*, type: Literal['add_tags'], tags: List[sigma.schema.RuleTag])¶

Bases: sigma.transform.Transformation.Schema

AddTags configuration definition

class Config¶

Bases: object

extra = 'forbid'¶

schema_extra = {'examples': [{'type': 'add_tags', 'tags': ['custom_tag1', 'custom_tag2', 'attack.t12345']}]}¶

tags: List[sigma.schema.RuleTag]¶

type: Literal['add_tags']¶: Name of the transformation type

transform_rule(rule: sigma.schema.Rule) → sigma.schema.Rule¶: Transform the given rule by either modifying it inline or returning an entirely new rule. The default implementation simply returns the original rule.

class sigma.transform.ContainsToMatch(schema: sigma.transform.Transformation.Schema)¶

Bases: sigma.transform.Transformation

Convert string contains field comparisons to a match with wildcards

transform_expression(rule: sigma.schema.Rule, expression: sigma.grammar.Expression) → sigma.grammar.Expression¶: Transform the given expression by either modifying it or returning an entirely new expression. This method is called recursively on each sub-expression, so you need-not evaluate sub-expressions explicitly. The default implementation simply returns the original expression.

class sigma.transform.ExpressionType(value)¶

Bases: str, enum.Enum

Defines the types of expressions we can modify

CONTAINS = 'contains'¶

ENDSWITH = 'endswith'¶

STARTSWITH = 'startswith'¶

class sigma.transform.FieldFuzzyMap(schema: sigma.transform.FieldFuzzyMap.Schema)¶

Bases: sigma.transform.Transformation

Replace field names with an explicit mapping. The configuration for this transformation is a mapping between Sigma field names and your backend field names. This version of a field map will replace field names ignoring case and also test against snake_case and CamelCase versions of the given fields. All source fields in the mapping should be in snake_case.

class Schema(*, type: Literal['field_fuzzy_map'], mapping: Dict[str, str], skip_unknown: bool = False)¶

Bases: sigma.transform.Transformation.Schema

Field mapping configuration definition

class Config¶

Bases: object

extra = 'forbid'¶

schema_extra = {'examples': [{'type': 'field_map', 'mapping': {'command_line': 'process.command_line', 'image': 'process.executable'}, 'skip_unknown': False}]}¶

mapping: Dict[str, str]¶: Field name mappings

skip_unknown: bool¶: Raise a SkipRule exception for fields that aren’t mapped

type: Literal['field_fuzzy_map']¶: Name of the transformation type

transform_expression(rule: sigma.schema.Rule, expression: sigma.grammar.Expression) → sigma.grammar.Expression¶: Replace any field names based on the provided mapping. If the expression is not a field comparison, this method simply returns the expression unaltered.

class sigma.transform.FieldMap(schema: sigma.transform.FieldMap.Schema)¶

Bases: sigma.transform.Transformation

Transform sigma rule expressions to replace field names. Transformation configuration is a mapping between built-in field names and custom field names.

Parameters: config (Dict[str, str]) – a mapping between built-in field names and custom field names

class Schema(*, type: Literal['field_map'], mapping: Dict[str, str], skip_unknown: bool = False)¶

Bases: sigma.transform.Transformation.Schema

Field mapping configuration definition

class Config¶

Bases: object

extra = 'forbid'¶

schema_extra = {'examples': [{'type': 'field_map', 'mapping': {'CommandLine': 'process.command_line', 'Image': 'process.executable'}, 'skip_unknown': False}]}¶

mapping: Dict[str, str]¶: Field name mappings

skip_unknown: bool¶: Raise a SkipRule exception for fields that aren’t mapped

type: Literal['field_map']¶: Name of the transformation type

transform_expression(rule: sigma.schema.Rule, expression: sigma.grammar.Expression) → sigma.grammar.Expression¶: Replace any field names based on the provided mapping. If the expression is not a field comparison, this method simply returns the expression unaltered.

class sigma.transform.FieldMatchReplace(schema: sigma.transform.FieldMatchReplace.Schema)¶

Bases: sigma.transform.Transformation

Transform a field matching expression with a matching value to a field equality comparison. This transformation accepts the following configs: field, pattern, target and type. The type is one of endswith, startswith or contains. The field is the name of the field being compared. Pattern is a regular expression which must match the value of the matching expression, and must also contain a regex group which will be substituted as value in the new equality expression. The target is the name of the field used in the new equality expression. If the target is not provided, the field is reused in the equality expression. As an example, the following config will replace endsWith(process.executable, "\\test.exe") with process.name == "test.exe".

class Schema(*, type: Literal['match_replace'], expression: sigma.transform.ExpressionType, field: str, pattern: Pattern, target: str = None)¶

Bases: sigma.transform.Transformation.Schema

Configuration schema for this transformation

class Config¶

Bases: object

extra = 'forbid'¶

schema_extra = {'examples': [{'type': 'match_replace', 'expression': 'endswith', 'field': 'process.executable', 'pattern': '\\\\(.*)', 'target': 'process.name'}]}¶

expression: sigma.transform.ExpressionType¶

field: str¶

pattern: Pattern¶

target: Optional[str]¶

type: Literal['match_replace']¶: Name of the transformation type

VALID_TYPES: Dict[str, Type[sigma.grammar.Expression]] = {ExpressionType.CONTAINS: <class 'sigma.grammar.FieldContains'>, ExpressionType.ENDSWITH: <class 'sigma.grammar.FieldEndsWith'>, ExpressionType.STARTSWITH: <class 'sigma.grammar.FieldStartsWith'>}¶

transform_expression(rule: sigma.schema.Rule, expression: sigma.grammar.FieldComparison) → sigma.grammar.Expression¶: Transform the given expression

class sigma.transform.Transformation(schema: sigma.transform.Transformation.Schema)¶

Bases: abc.ABC

Base transformation class for inline modification during rule serialization

Parameters: type (str) – type of transformation

class Schema(*, type: str, **extra_data: Any)¶

Bases: pydantic.main.BaseModel

Common transformation configuration schema. Specific transforms extend this class to provide structured configuration information.

class Config¶

Bases: object

extra = 'allow'¶

load() → sigma.transform.Transformation¶: Construct a transformation instance from the schema.

type: str¶: Name of the transformation type

classmethod enumerate_builtin() → Generator[Tuple[str, str], None, None]¶: Enumerate all built-in transformations. This method yields tuples of (name, description) for each built-in transformation.

classmethod lookup_class(name: str) → Type[sigma.transform.Transformation]¶: Lookup the class backing the given transformation type name or fully-qualified class name

transform_expression(rule: sigma.schema.Rule, expression: sigma.grammar.Expression) → sigma.grammar.Expression¶: Transform the given expression by either modifying it or returning an entirely new expression. This method is called recursively on each sub-expression, so you need-not evaluate sub-expressions explicitly. The default implementation simply returns the original expression.

transform_rule(rule: sigma.schema.Rule) → sigma.schema.Rule¶: Transform the given rule by either modifying it inline or returning an entirely new rule. The default implementation simply returns the original rule.

transform_serializer(serializer: Serializer, rule: sigma.schema.Rule) → ContextManager¶: Transform the given serializer for this rule. The transformation must be temporary, and must be removed when the context manager exits. Some serializer-specific configurations not specified in the sigma spec could be done here.

sigma.transform package¶

Transformation Schema¶

Table of Contents

Related Topics

This Page