Breaking Changes

This page documents breaking changes in pySigma. Normally, we try to avoid breaking changes in minor versions and generally try to keep pySigma backwards compatible, but sometimes they are necessary to improve the library.

Version 1.0

  • The class CompareOperators was moved out of SigmaCompatreExpression into the root of the containing module sigma.types. If the class was formerly used, it has now to be imported explicitly from the module.

  • Initialization of a SigmaDetectionItem doesn’t converts plain types to SigmaType objects anymore and expects a list as value. Use SigmaDetectionItem.from_mapping() or .from_value() instead.

  • SigmaCollection.from_yaml(), .from_dicts() new parameter collect_filters introduced at position after collect_errors.

  • SigmaCollection() constructor new parameter collect_filters introduced at position after errors.

  • SigmaPipelineConditionError: parameter ordering changed, expression and location are now optional.

  • QueryPostprocessingTransformation introduces apply_query() method for clear distinction of methods for different processing stages.

  • Functionality of inherited classes was consolidated into FieldMappingTransformationBase. The method get_mapping from FieldMappingTransformation and all classes inherited from it was consolidated into apply_field_name. Usually, it should be sufficient to replace get_mapping() with apply_field_name() if it was overridden in a subclass.

  • Validator config now uses identifier (filename_length) instead of class name (FilenameLengthValidator) to establish consistency with remaining config.

  • SigmaValueValidator.validated_types was removed. Instead the type has to be checked in the validate_value method.

  • The validation logic of a class inherited by SigmaStringValueValidator is now implemented in a validate_string method instead of validate_value.

  • The ProcessingPipeline is only initialized once per backend instantiation instead of once per converted rule. The state dict is reset for each call to apply().

  • The references to the using pipeline of objects derived from classess inheriting from ProcessingItem, Transformation, RuleCondition, DetectionItemCondition and FieldNameCondition can only be set once. Further attempts will raise an exception. This implies that such objects can’t be re-used in a pipeline (e.g. as variable), but have to be instantiated again for each usage (e.g. via factory).

  • The type parameter of IncludeFieldCondition and ExcludeFieldCondition was renamed to mode.

  • Query finalization in rule conversion was splitted into a finish step that is intended to amend the query, e.g. for handling deferred expressions or field selections and finalization for conversion into the target output format. The main difference is that the finalization step normally isn’t executed for correlation rules while finish is.

  • Migrated to pyYAML CSafeLoader.

  • SigmaCollection now resolves rule references by default on initialization. This behavior can be disabled with the optional resolve_references parameter.

  • MITRE ATT&CK and D3FEND data is now downloaded on-demand instead of being shipped with the library. In restricted environments, use mitre_attack_data.set_url() and mitre_d3fend_data.set_url() to load data from local files. The content should be accessed only if really used to avoid performance hit by unwanted downloads.

  • Python 3.10+ required: The minimum required Python version has been updated from 3.9 to 3.10. Python 3.9 reached end-of-life and is no longer supported. Users must upgrade to Python 3.10 or later to use this version of pySigma.