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

__init__()

Initializes an event filter.

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

__init__()

Initializes an event filter expression parser.

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

__init__(state, regex, actions, next_state)

Initializes an event filter expressions parser token.

Parameters:

• state (str) – parser state within the token should be applied or None if the token should be applied regardless of the parser state.

• regex (str) – regular expression to try and match from the current point.

• actions (list[str]) – list of method names in the EventFilterExpressionParser to call.

• next_state (str) – next state we transition to if this Token matches.

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.

__init__(operator='')

Initializes an event filter parser binary expression.

Parameters:

operator (str) – operator, such as “and” or “&&”.

__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.

__init__()

Initializes an event 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.

__init__()

Initializes an event filter parser expression.

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.

__init__()

Initializes a date and time-based file entry filter.

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.

__init__(extensions)

Initializes an extensions-based file entry filter.

An extension is defined as “pdf” as in “document.pdf”.

Parameters:

extensions (list[str]) – a list of extension strings.

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.

__init__()

Initializes a file entry filter collection.

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.

__init__(names)

Initializes a names-based file entry filter.

Parameters:

names (list[str]) – names.

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.

__init__(specification_store, signature_identifiers)

Initializes a signature-based file entry filter.

Parameters:

• specification_store (FormatSpecificationStore) – a specification store.

• signature_identifiers (list[str]) – signature identifiers.

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

__init__(arguments=None, **kwargs)

Initializes a binary operator.

Parameters:

arguments (Optional[list[str, object]]) – operands of the filter.

Raises:

InvalidNumberOfOperands – if the number of operands provided is not supported.

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

__init__(arguments=None)

Initializes a filter.

Implementations expanders are provided by subclassing ValueExpander.

Parameters:

arguments (Optional[object]) – arguments.

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

__init__(arguments=None, **kwargs)

Initializes a generic binary operator.

Parameters:

arguments (Optional[list[str, object]]) – operands of the filter.

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:

???

__init__(arguments=None, **kwargs)

Initializes a regular expression operator.

This operator uses case sensitive comparison.

Parameters:

arguments (Optional[object]) – operands of the filter.

Raises:

ValueError – if the regular expression is malformed.

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

Bases: Regexp

Operator to determine if a value matches a regular expression.

__init__(arguments=None, **kwargs)

Initializes a regular expression operator.

This operator uses case insensitive comparison.

Parameters:

arguments (Optional[object]) – operands of the filter.

Raises:

ValueError – if the regular expression is malformed.

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

__init__(paths, case_sensitive=True, path_segment_separator='/')

Initializes and builds a path filter scan tree.

Parameters:

• paths (list[str]) – paths.

• case_sensitive (Optional[bool]) – True if string matches should be case sensitive.

• path_segment_separator (Optional[str]) – path segment separator.

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

__init__(path_segment_index)

Initializes a path filter scan tree node.

Parameters:

path_segment_index (int) – path segment index.

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.

__init__(value)

Initializes a date and time value type.

Parameters:

(int (value) – str): a POSIX timestamp in microseconds or an ISO 8601 date and time string.

Raises:

ValueError – if the value cannot be copied to a date and time object.

Module contents