plaso.filters package

Submodules

plaso.filters.event_filter module

The event filter.

class plaso.filters.event_filter.EventObjectFilter

Bases: object

Event filter.

CompileFilter(filter_expression)

Compiles the filter expression.

The filter expression contains an object filter expression.

Parameters

filter_expression (str) – filter expression.

Raises

ParseError – if the filter expression cannot be parsed.

Match(event, event_data, event_data_stream, event_tag)

Determines if an event matches the filter.

Parameters

• event (EventObject) – event.

• event_data (EventData) – event data.

• event_data_stream (EventDataStream) – event data stream.

• event_tag (EventTag) – event tag.

Returns

True if the event matches the filter, False otherwise.

Return type

bool

plaso.filters.expression_parser module

Event filter expression parser.

class plaso.filters.expression_parser.EventFilterExpressionParser

Bases: object

Event filter expression parser.

Examples of valid syntax:

size is 40 (name contains “Program Files” AND hash.md5 is “123abc”) @imported_modules (num_symbols = 14 AND symbol.name is “FindWindow”)

HexEscape(string, match, **unused_kwargs)

Converts a hex escaped string.

Note that this function is used as a callback by _GetNextToken.

Returns

next state, which is None.

Return type

str

Raises

ParseError – if the string is not hex escaped.

Parse(expression)

Parses an event filter expression.

Parameters

expression (str) – event filter expression.

Returns

expression.

Return type

Expression

class plaso.filters.expression_parser.Token(state, regex, actions, next_state)

Bases: object

An event filter expression parser token.

actions

list of method names in the EventFilterExpressionParser to call.

Type

list[str]

next_state

next state we transition to if this Token matches.

Type

str

state

parser state within the token should be applied or None if the token should be applied regardless of the parser state.

Type

str

CompareExpression(expression)

Compares the token against an expression string.

Parameters

expression (str) – expression string.

Returns

the regular expression match object if the expression string

matches the token or None if no match.

Return type

re.Match

plaso.filters.expressions module

The event filter expression parser expression classes.

class plaso.filters.expressions.BinaryExpression(operator='')

Bases: Expression

An event filter parser expression which takes two other expressions.

AddOperands(lhs, rhs)

Adds an operand.

Parameters

• lhs (Expression) – left hand side expression.

• rhs (Expression) – right hand side expression.

Raises

ParseError – if either left hand side or right hand side expression is not an instance of Expression.

Compile()

Compiles the expression into a filter.

Returns

filter object corresponding the expression.

Return type

Filter

Raises

ParseError – if the operator is not supported.

__repr__()

Retrieves a string representation of the object for debugging.

class plaso.filters.expressions.EventExpression

Bases: Expression

Event expression.

Compile()

Compiles the expression into a filter.

Returns

filter object corresponding the expression.

Return type

Filter

Raises

ParseError – if the operator is missing or unknown.

Negate()

Reverses the logic of (negates) the expression.

__repr__()

Retrieves a string representation of the object for debugging.

class plaso.filters.expressions.Expression

Bases: object

An event filter parser expression.

attribute

attribute or None if not set.

Type

str

args

arguments.

Type

list[object]

number_of_args

expected number of arguments.

Type

int

operator

operator or None if not set.

Type

str

AddArgument(argument)

Adds a new argument to this expression.

Parameters

argument (object) – argument to add.

Returns

True if the argument is the last argument, False otherwise.

Return type

bool

Raises

ParseError – If there are too many arguments.

abstract Compile()

Compiles the expression into a filter.

Returns

filter object corresponding the expression.

Return type

Filter

SetAttribute(attribute)

Sets the attribute.

Parameters

attribute (str) – attribute, or None if not set.

SetOperator(operator)

Set the operator.

Parameters

operator (str) – operator, such as “and” or “&&”, or None if not set.

attribute = None

class plaso.filters.expressions.IdentityExpression

Bases: Expression

An event filter parser expression which always evaluates to True.

Compile()

Compiles the expression into a filter.

Returns

filter object which always evaluates to True.

Return type

IdentityFilter

plaso.filters.file_entry module

File entry filters.

class plaso.filters.file_entry.DateTimeFileEntryFilter

Bases: FileEntryFilter

Date and time-based file entry filter.

AddDateTimeRange(time_value, start_time_string=None, end_time_string=None)

Adds a date time filter range.

The time strings are formatted as: YYYY-MM-DD hh:mm:ss.######[+-]##:## Where # are numeric digits ranging from 0 to 9 and the seconds fraction can be either 3 or 6 digits. The time of day, seconds fraction and timezone offset are optional. The default timezone is UTC.

Parameters

• time_value (str) – time value, such as, atime, ctime, crtime, dtime, bkup and mtime.

• start_time_string (str) – start date and time value string.

• end_time_string (str) – end date and time value string.

Raises

ValueError – If the filter is badly formed.

Matches(file_entry)

Compares the file entry against the filter.

Parameters

file_entry (dfvfs.FileEntry) – file entry to compare.

Returns

True if the file entry matches the filter, False if not or

None if the filter does not apply.

Return type

bool

Print(output_writer)

Prints a human readable version of the filter.

Parameters

output_writer (CLIOutputWriter) – output writer.

class plaso.filters.file_entry.ExtensionsFileEntryFilter(extensions)

Bases: FileEntryFilter

Extensions-based file entry filter.

Matches(file_entry)

Compares the file entry against the filter.

Parameters

file_entry (dfvfs.FileEntry) – file entry to compare.

Returns

True if the file entry matches the filter, False if not or

None if the filter does not apply.

Return type

bool

Print(output_writer)

Prints a human readable version of the filter.

Parameters

output_writer (CLIOutputWriter) – output writer.

class plaso.filters.file_entry.FileEntryFilter

Bases: object

File entry filter interface.

abstract Matches(file_entry)

Compares the file entry against the filter.

Parameters

file_entry (dfvfs.FileEntry) – file entry to compare.

Returns

True if the file entry matches the filter, False if not or

None if the filter does not apply.

Return type

bool

abstract Print(output_writer)

Prints a human readable version of the filter.

Parameters

output_writer (CLIOutputWriter) – output writer.

class plaso.filters.file_entry.FileEntryFilterCollection

Bases: object

Collection of file entry filters.

AddFilter(file_entry_filter)

Adds a file entry filter to the collection.

Parameters

file_entry_filter (FileEntryFilter) – file entry filter.

HasFilters()

Determines if filters are defined.

Returns

True if filters are defined.

Return type

bool

Matches(file_entry)

Compares the file entry against the filter collection.

Parameters

file_entry (dfvfs.FileEntry) – file entry to compare.

Returns

True if the file entry matches one of the filters. If no filters

are provided or applicable the result will be True.

Return type

bool

Print(output_writer)

Prints a human readable version of the filter.

Parameters

output_writer (CLIOutputWriter) – output writer.

class plaso.filters.file_entry.NamesFileEntryFilter(names)

Bases: FileEntryFilter

Names-based file entry filter.

Matches(file_entry)

Compares the file entry against the filter.

Parameters

file_entry (dfvfs.FileEntry) – file entry to compare.

Returns

True if the file entry matches the filter.

Return type

bool

Print(output_writer)

Prints a human readable version of the filter.

Parameters

output_writer (CLIOutputWriter) – output writer.

class plaso.filters.file_entry.SignaturesFileEntryFilter(specification_store, signature_identifiers)

Bases: FileEntryFilter

Signature-based file entry filter.

Matches(file_entry)

Compares the file entry against the filter.

Parameters

file_entry (dfvfs.FileEntry) – file entry to compare.

Returns

True if the file entry matches the filter, False if not or

None if the filter does not apply.

Return type

bool

Print(output_writer)

Prints a human readable version of the filter.

Parameters

output_writer (CLIOutputWriter) – output writer.

plaso.filters.filters module

The event filter expression parser filter classes.

class plaso.filters.filters.AndFilter(arguments=None)

Bases: Filter

A filter that performs a boolean AND on the arguments.

Note that if no conditions are passed, all objects will pass.

Matches(event, event_data, event_data_stream, event_tag)

Determines if the event, data and tag match the filter.

Parameters

• event (EventObject) – event to compare against the filter.

• event_data (EventData) – event data to compare against the filter.

• event_data_stream (EventDataStream) – event data stream.

• event_tag (EventTag) – event tag to compare against the filter.

Returns

True if the event, data and tag match the filter, False otherwise.

Return type

bool

class plaso.filters.filters.BinaryOperator(arguments=None, **kwargs)

Bases: Operator

Interface for binary operators.

left_operand

left hand operand.

Type

object

right_operand

right hand operand.

Type

object

abstract Matches(event, event_data, event_data_stream, event_tag)

Determines if the event, data and tag match the filter.

Parameters

• event (EventObject) – event to compare against the filter.

• event_data (EventData) – event data to compare against the filter.

• event_data_stream (EventDataStream) – event data stream.

• event_tag (EventTag) – event tag to compare against the filter.

Returns

True if the event, data and tag match the filter, False otherwise.

Return type

bool

class plaso.filters.filters.Contains(arguments=None, **kwargs)

Bases: GenericBinaryOperator

Operator to determine if a value contains another value.

class plaso.filters.filters.EqualsOperator(arguments=None, **kwargs)

Bases: GenericBinaryOperator

Equals (==) operator.

class plaso.filters.filters.Filter(arguments=None)

Bases: object

Filter interface.

args

arguments provided to the filter.

Type

list[object]

abstract Matches(event, event_data, event_data_stream, event_tag)

Determines if the event, data and tag match the filter.

Parameters

• event (EventObject) – event to compare against the filter.

• event_data (EventData) – event data to compare against the filter.

• event_data_stream (EventDataStream) – event data stream.

• event_tag (EventTag) – event tag to compare against the filter.

Returns

True if the event, data and tag match the filter, False otherwise.

Return type

bool

class plaso.filters.filters.GenericBinaryOperator(arguments=None, **kwargs)

Bases: BinaryOperator

Shared functionality for common binary operators.

FlipBool()

Negates the internal boolean value attribute.

Matches(event, event_data, event_data_stream, event_tag)

Determines if the event, data and tag match the filter.

Parameters

• event (EventObject) – event to compare against the filter.

• event_data (EventData) – event data to compare against the filter.

• event_data_stream (EventDataStream) – event data stream.

• event_tag (EventTag) – event tag to compare against the filter.

Returns

True if the event, data and tag match the filter, False otherwise.

Return type

bool

class plaso.filters.filters.GreaterEqualOperator(arguments=None, **kwargs)

Bases: GenericBinaryOperator

Greater than or equals (>=) operator.

class plaso.filters.filters.GreaterThanOperator(arguments=None, **kwargs)

Bases: GenericBinaryOperator

Greater than (>) operator.

class plaso.filters.filters.IdentityFilter(arguments=None)

Bases: Operator

A filter which always evaluates to True.

Matches(event, event_data, event_data_stream, event_tag)

Determines if the event, data and tag match the filter.

Parameters

• event (EventObject) – event to compare against the filter.

• event_data (EventData) – event data to compare against the filter.

• event_data_stream (EventDataStream) – event data stream.

• event_tag (EventTag) – event tag to compare against the filter.

Returns

True if the event, data and tag match the filter, False otherwise.

Return type

bool

class plaso.filters.filters.InSet(arguments=None, **kwargs)

Bases: GenericBinaryOperator

Operator to determine if a value is part of another value.

class plaso.filters.filters.LessEqualOperator(arguments=None, **kwargs)

Bases: GenericBinaryOperator

Less than or equals (<=) operator.

class plaso.filters.filters.LessThanOperator(arguments=None, **kwargs)

Bases: GenericBinaryOperator

Less than (<) operator.

class plaso.filters.filters.NotEqualsOperator(arguments=None, **kwargs)

Bases: GenericBinaryOperator

Not equals (!=) operator.

class plaso.filters.filters.Operator(arguments=None)

Bases: Filter

Interface for filters that represent operators.

abstract Matches(event, event_data, event_data_stream, event_tag)

Determines if the event, data and tag match the filter.

Parameters

• event (EventObject) – event to compare against the filter.

• event_data (EventData) – event data to compare against the filter.

• event_data_stream (EventDataStream) – event data stream.

• event_tag (EventTag) – event tag to compare against the filter.

Returns

True if the event, data and tag match the filter, False otherwise.

Return type

bool

class plaso.filters.filters.OrFilter(arguments=None)

Bases: Filter

A filter that performs a boolean OR on the arguments.

Note that if no conditions are passed, all objects will pass.

Matches(event, event_data, event_data_stream, event_tag)

Determines if the event, data and tag match the filter.

Parameters

• event (EventObject) – event to compare against the filter.

• event_data (EventData) – event data to compare against the filter.

• event_data_stream (EventDataStream) – event data stream.

• event_tag (EventTag) – event tag to compare against the filter.

Returns

True if the event, data and tag match the filter, False otherwise.

Return type

bool

class plaso.filters.filters.Regexp(arguments=None, **kwargs)

Bases: GenericBinaryOperator

Operator to determine if a value matches a regular expression.

compiled_re

compiled regular expression.

Type

???

class plaso.filters.filters.RegexpInsensitive(arguments=None, **kwargs)

Bases: Regexp

Operator to determine if a value matches a regular expression.

plaso.filters.logger module

The filters sub module logger.

plaso.filters.parser_filter module

Helper for parser and plugin filter expressions.

class plaso.filters.parser_filter.ParserFilterExpressionHelper

Bases: object

Helper for parser and plugin filter expressions.

A parser filter expression is a comma separated value string that denotes which parsers and plugins should be used. Each element can contain either:

• The name of a preset (case sensitive), which is a predefined list of parsers and/or plugins (see data/presets.yaml for the default presets).

• The name of a parser (case insensitive), for example ‘msiecf’.

• The name of a plugin, prefixed with the parser name and a ‘/’, for example ‘sqlite/chrome_history’.

If the element begins with an exclamation mark (‘!’) the item will be excluded from the set of enabled parsers and plugins, otherwise the element will be included.

ExpandPresets(presets_manager, expression)

Expands all presets in a parser filter expression.

Parameters

• presets_manager (ParserPresetsManager) – a parser preset manager, that is used to resolve which parsers and/or plugins are defined by presets.

• expression (str) –

  parser filter expression, where an empty expression represents all parsers and plugins.

  A parser filter expression is a comma separated value string that denotes which parsers and plugins should be used. Each element can be either:

  • The name of a preset (case sensitive), which is a predefined list of parsers and/or plugins (see data/presets.yaml for the default presets).

  • The name of a parser (case insensitive), for example ‘msiecf’.

  • The name of a plugin, prefixed with the parser name and a ‘/’, for example ‘sqlite/chrome_history’.

  If the element begins with an exclamation mark (‘!’) the item will be excluded from the set of enabled parsers and plugins, otherwise the element will be included.

Returns

a parser filter expression where presets have been expanded or None

to represent all parsers and plugins.

Return type

str

SplitExpression(expression)

Determines the excluded and included elements in an expression string.

This method will not expand presets, and preset names are treated like parser names.

Parameters

expression (str) –

parser filter expression.

A parser filter expression is a comma separated value string that denotes which parsers and plugins should be used. Each element can be either:

• The name of a preset (case sensitive), which is a predefined list of parsers and/or plugins (see data/presets.yaml for the default presets).

• The name of a parser (case insensitive), for example ‘msiecf’.

• The name of a plugin, prefixed with the parser name and a ‘/’, for example ‘sqlite/chrome_history’.

If the element begins with an exclamation mark (‘!’) the item will be excluded from the set of enabled parsers and plugins, otherwise the element will be included.

Returns

containing:

excludes (dict[str, set[str]]): excluded presets, plugins and presets.

Dictionary keys are preset and/or parser names, and values are sets containing plugin names to enable for a parser or an asterisk character (‘*’) to represent all plugins, or that no specific plugins were specified.

includes (dict[str, set[str]]): included presets, parsers and plugins.

Dictionary keys are preset and/or parser names, and values are sets containing plugin names to enable for a parser or an asterisk character (‘*’) to represent all plugins, or that no specific plugins were specified.

Return type

tuple

plaso.filters.path_filter module

A scan tree-based path filter implementation.

The scan tree is a tree based on multiple paths that contains the path segments per node. The most significant path segment is at the root and therefore compared first. More information can be found here: https://github.com/libyal/libsigscan/wiki/Internals#scanning-tree-based-signature-scanning

The scan tree is used in the filter to filter provided paths.

class plaso.filters.path_filter.PathFilterScanTree(paths, case_sensitive=True, path_segment_separator='/')

Bases: object

Path filter scan tree.

CheckPath(path, path_segment_separator=None)

Checks if a path matches the scan tree-based path filter.

Parameters

• path (str) – path.

• path_segment_separator (Optional[str]) – path segment separator, where None defaults to the path segment separator that was set when the path filter scan tree was initialized.

Returns

True if the path matches the filter, False otherwise.

Return type

bool

class plaso.filters.path_filter.PathFilterScanTreeNode(path_segment_index)

Bases: object

Class that implements a path filter scan tree node.

The path filter scan tree node defines the path segments for a specific path segment index to filter. Each path segment will point to a scan object that indicates the next part of the path filter. A default value indicates the scan object to use next when there was no match.

default_value

the default scan object, which is either a scan tree sub node or a path.

Type

str|PathFilterScanTreeNode

parent

the parent path filter scan tree node or None if the node has no parent.

Type

PathFilterScanTreeNode

path_segment_index

path segment index represented by the node.

Type

int

AddPathSegment(path_segment, scan_object)

Adds a path segment.

Parameters

• path_segment (str) – path segment.

• scan_object (str|PathFilterScanTreeNode) – a scan object, which is either a scan tree sub node or a path.

Raises

ValueError – if the node already contains a scan object for the path segment.

GetScanObject(path_segment)

Retrieves the scan object for a specific path segment.

Parameters

path_segment (str) – path segment.

Returns

a scan object, which is either

a scan tree sub node, a path or the default value.

Return type

str|PathFilterScanTreeNode

SetDefaultValue(scan_object)

Sets the default (non-match) value.

Parameters

scan_object (str|PathFilterScanTreeNode) – a scan object, which is either a scan tree sub node or a path.

Raises

• TypeError – if the scan object is of an unsupported type.

• ValueError – if the default value is already set.

ToDebugString(indentation_level=1)

Converts the path filter scan tree node into a debug string.

Parameters

indentation_level (int) – text indentation level.

Returns

debug string representing the path filter scan tree node.

Return type

str

property path_segments

path segments.

Type

list[str]

plaso.filters.value_types module

Value types that can be used in an event filter.

class plaso.filters.value_types.DateTimeValueType(*args: Any, **kwargs: Any)

Bases: PosixTimeInMicroseconds

Value type to represent a date and time value.

Module contents