observation

Transformation utilities for STIX pattern observation expressions.

class AbsorptionTransformer

Applies boolean “absorption” rules for observation expressions, for AST simplification:

A or (A and B) = A A or (A followedby B) = A A or (B followedby A) = A

Other variants do not hold for observation expressions.

transform_or(ast)

class DNFTransformer

Transform an observation expression to DNF. This will distribute AND and FOLLOWEDBY over OR:

A and (B or C) => (A and B) or (A and C) A followedby (B or C) => (A followedby B) or (A followedby C) (A or B) followedby C => (A followedby C) or (B followedby C)

transform_and(ast)

transform_followedby(ast)

class FlattenTransformer

Flatten an observation expression AST. E.g.:

A and (B and C) => A and B and C A or (B or C) => A or B or C A followedby (B followedby C) => A followedby B followedby C (A) => A

transform_and(ast)

transform_followedby(ast)

transform_or(ast)

class NormalizeComparisonExpressionsTransformer

Normalize all comparison expressions.

transform_observation(ast)

class ObservationExpressionTransformer

Transformer base class with special support for transforming observation expressions. The transform method implemented here performs a bottom-up in-place transformation, with support for some observation expression-specific callbacks. It recurses down as far as the “leaf node” observation expressions; it does not go inside of them, to the individual components of a comparison expression.

Specifically, subclasses can implement methods:

“transform_or” for OR nodes “transform_and” for AND nodes “transform_followedby” for FOLLOWEDBY nodes “transform_qualified” for qualified nodes (all qualifier types) “transform_observation” for “leaf” observation expression nodes “transform_default” for all types of nodes

“transform_default” is a fallback, if a type-specific callback is not found. The default implementation does nothing to the AST. The type-specific callbacks are preferred over the default, if both exist.

In all cases, the callbacks are called with an AST for a subtree rooted at the appropriate node type, where the AST’s children have already been transformed. They must return the same thing as the base transform() method: a 2-tuple with the transformed AST and a boolean for change detection. See doc for the superclass’ method.

This process currently silently drops parenthetical nodes.

transform(ast)

Transform the given AST and return the resulting AST.

Parameters:ast – The AST to transform Returns:A 2-tuple: the transformed AST and a boolean indicating whether the transformation actually changed anything. The change detection is useful in situations where a transformation needs to be repeated until the AST stops changing.

transform_default(ast)

class OrderDedupeTransformer

Order AND/OR expressions, and dedupe ORs. E.g.:

A or A => A B or A => A or B B and A => A and B

transform_and(ast)

transform_or(ast)