plaso.filters package

Submodules

plaso.filters.event_filter module

The event filter.

class plaso.filters.event_filter.EventObjectFilter[source]

Bases: plaso.filters.interface.FilterObject

Event filter.

CompileFilter(filter_expression)[source]

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_tag)[source]

Determines if an event matches the filter.

Parameters
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[source]

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”)

Default(**kwarg)[source]

Default callback handler.

HexEscape(string, match, **unused_kwargs)[source]

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.

InsertArg(string='', **unused_kwargs)[source]

Inserts an argument into the current expression.

Parameters

string (Optional[str]) – argument string.

Returns

state or None if the argument could not be added to the current

expression.

Return type

str

Raises

ParseError – if the operator does not support negation.

InsertFloatArg(string='', **unused_kwargs)[source]

Inserts a floating-point argument into the current expression.

Parameters

string (Optional[str]) – argument string that contains a floating-point value.

Returns

state or None if the argument could not be added to the current

expression.

Return type

str

Raises

ParseError – TBD.

InsertInt16Arg(string='', **unused_kwargs)[source]

Inserts a hexadecimal integer argument into the current expression.

Parameters

string (Optional[str]) – argument string that contains an integer value formatted in hexadecimal.

Returns

state or None if the argument could not be added to the current

expression.

Return type

str

Raises

ParseError – if string does not contain a valid base16 formatted integer.

InsertIntArg(string='', **unused_kwargs)[source]

Inserts a decimal integer argument into the current expression.

Parameters

string (Optional[str]) – argument string that contains an integer value formatted in decimal.

Returns

state or None if the argument could not be added to the current

expression.

Return type

str

Raises

ParseError – if string does not contain a valid integer.

Parse(expression)[source]

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)[source]

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

re_str

regular expression to try and match from the current point.

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)[source]

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='')[source]

Bases: plaso.filters.expressions.Expression

An event filter parser expression which takes two other expressions.

AddOperands(lhs, rhs)[source]

Adds an operand.

Parameters
Raises

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

Compile()[source]

Compiles the expression into a filter.

Returns

filter object corresponding the expression.

Return type

Filter

Raises

ParseError – if the operator is not supported.

class plaso.filters.expressions.EventExpression[source]

Bases: plaso.filters.expressions.Expression

Event expression.

Compile()[source]

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()[source]

Reverses the logic of (negates) the expression.

class plaso.filters.expressions.Expression[source]

Bases: object

An event filter parser expression.

attribute

attribute or None if not set.

Type

str

args

arguments.

Type

list[str]

number_of_args

expected number of arguments.

Type

int

operator

operator or None if not set.

Type

str

AddArg(argument)[source]

Adds a new argument to this expression.

Parameters

argument (str) – 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.

Compile()[source]

Compiles the expression into a filter.

Returns

filter object corresponding the expression.

Return type

Filter

SetAttribute(attribute)[source]

Sets the attribute.

Parameters

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

SetOperator(operator)[source]

Set the operator.

Parameters

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

attribute = None
class plaso.filters.expressions.IdentityExpression[source]

Bases: plaso.filters.expressions.Expression

An event filter parser expression which always evaluates to True.

Compile()[source]

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[source]

Bases: plaso.filters.file_entry.FileEntryFilter

Date and time-based file entry filter.

AddDateTimeRange(time_value, start_time_string=None, end_time_string=None)[source]

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)[source]

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)[source]

Prints a human readable version of the filter.

Parameters

output_writer (CLIOutputWriter) – output writer.

class plaso.filters.file_entry.ExtensionsFileEntryFilter(extensions)[source]

Bases: plaso.filters.file_entry.FileEntryFilter

Extensions-based file entry filter.

Matches(file_entry)[source]

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)[source]

Prints a human readable version of the filter.

Parameters

output_writer (CLIOutputWriter) – output writer.

class plaso.filters.file_entry.FileEntryFilter[source]

Bases: object

File entry filter interface.

Matches(file_entry)[source]

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)[source]

Prints a human readable version of the filter.

Parameters

output_writer (CLIOutputWriter) – output writer.

class plaso.filters.file_entry.FileEntryFilterCollection[source]

Bases: object

Collection of file entry filters.

AddFilter(file_entry_filter)[source]

Adds a file entry filter to the collection.

Parameters

file_entry_filter (FileEntryFilter) – file entry filter.

HasFilters()[source]

Determines if filters are defined.

Returns

True if filters are defined.

Return type

bool

Matches(file_entry)[source]

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)[source]

Prints a human readable version of the filter.

Parameters

output_writer (CLIOutputWriter) – output writer.

class plaso.filters.file_entry.NamesFileEntryFilter(names)[source]

Bases: plaso.filters.file_entry.FileEntryFilter

Names-based file entry filter.

Matches(file_entry)[source]

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)[source]

Prints a human readable version of the filter.

Parameters

output_writer (CLIOutputWriter) – output writer.

class plaso.filters.file_entry.SignaturesFileEntryFilter(specification_store, signature_identifiers)[source]

Bases: plaso.filters.file_entry.FileEntryFilter

Signature-based file entry filter.

Matches(file_entry)[source]

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)[source]

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)[source]

Bases: plaso.filters.filters.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_tag)[source]

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_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)[source]

Bases: plaso.filters.filters.Operator

Interface for binary operators.

left_operand

left hand operand.

Type

object

right_operand

right hand operand.

Type

object

Matches(event, event_data, event_tag)[source]

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_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)[source]

Bases: plaso.filters.filters.GenericBinaryOperator

Operator to determine if a value contains another value.

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

Bases: plaso.filters.filters.GenericBinaryOperator

Equals (==) operator.

class plaso.filters.filters.Filter(arguments=None)[source]

Bases: object

Filter interface.

args

arguments provided to the filter.

Type

list[object]

Matches(event, event_data, event_tag)[source]

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_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)[source]

Bases: plaso.filters.filters.BinaryOperator

Shared functionality for common binary operators.

FlipBool()[source]

Negates the internal boolean value attribute.

Matches(event, event_data, event_tag)[source]

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_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)[source]

Bases: plaso.filters.filters.GenericBinaryOperator

Greater than or equals (>=) operator.

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

Bases: plaso.filters.filters.GenericBinaryOperator

Greater than (>) operator.

class plaso.filters.filters.IdentityFilter(arguments=None)[source]

Bases: plaso.filters.filters.Operator

A filter which always evaluates to True.

Matches(event, event_data, event_tag)[source]

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_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)[source]

Bases: plaso.filters.filters.GenericBinaryOperator

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

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

Bases: plaso.filters.filters.GenericBinaryOperator

Less than or equals (<=) operator.

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

Bases: plaso.filters.filters.GenericBinaryOperator

Less than (<) operator.

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

Bases: plaso.filters.filters.GenericBinaryOperator

Not equals (!=) operator.

class plaso.filters.filters.Operator(arguments=None)[source]

Bases: plaso.filters.filters.Filter

Interface for filters that represent operators.

Matches(event, event_data, event_tag)[source]

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_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)[source]

Bases: plaso.filters.filters.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_tag)[source]

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_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)[source]

Bases: plaso.filters.filters.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)[source]

Bases: plaso.filters.filters.Regexp

Operator to determine if a value matches a regular expression.

plaso.filters.helpers module

The event filter expression parser helper functions and classes.

class plaso.filters.helpers.DateCompareObject(data)[source]

Bases: object

A specific class created for date comparison.

This object takes a date representation, whether that is a direct integer datetime object or a string presenting the date, and uses that for comparing against timestamps stored in microseconds in in microseconds since Jan 1, 1970 00:00:00 UTC.

This makes it possible to use regular comparison operators for date, irrelevant of the format the date comes in, since plaso stores all timestamps in the same format, which is an integer/long, it is a simple manner of changing the input into the same format (int) and compare that.

__cmp__(x)[source]

A simple comparison operation.

Parameters

x (object) – object to compare against.

Returns

True if self is equal to the object.

Return type

bool

__eq__(x)[source]

Check if equal.

Parameters

x (object) – object to compare against.

Returns

True if self is equal to the object.

Return type

bool

__ge__(x)[source]

Greater or equal comparison.

Parameters

x (object) – object to compare against.

Returns

True if self is greater than or equal to the object.

Return type

bool

__gt__(x)[source]

Greater comparison.

Parameters

x (object) – object to compare against.

Returns

True if self is greater than the object.

Return type

bool

__le__(x)[source]

Less or equal comparison.

Parameters

x (object) – object to compare against.

Returns

True if self is less than or equal to the object.

Return type

bool

__lt__(x)[source]

Less comparison.

Parameters

x (object) – object to compare against.

Returns

True if self is less than the object.

Return type

bool

__ne__(x)[source]

Check if not equal.

Parameters

x (object) – object to compare against.

Returns

True if self is not equal to the object.

Return type

bool

__str__()[source]

Retrieves a string representation of the object.

Returns

string representation of the object.

Return type

str

plaso.filters.helpers.GetUnicodeString(value)[source]

Attempts to convert the argument to a Unicode string.

Parameters

value (list|int|bytes|str) – value to convert.

Returns

string representation of the argument.

Return type

str

class plaso.filters.helpers.TimeRangeCache[source]

Bases: object

A class that stores time ranges from filters.

classmethod GetTimeRange()[source]

Return the first and last timestamp of filter range.

MAX_INT64 = 18446744073709551615
classmethod SetLowerTimestamp(timestamp)[source]

Sets the lower bound timestamp.

classmethod SetUpperTimestamp(timestamp)[source]

Sets the upper bound timestamp.

plaso.filters.interface module

Filter interface.

class plaso.filters.interface.FilterObject[source]

Bases: object

Filter object interface.

CompileFilter(filter_expression)[source]

Compiles the filter expression.

Parameters

filter_expression (str) – filter expression.

Raises

WrongPlugin – if the filter could not be compiled.

Match(event, event_data, event_tag)[source]

Determines if an event matches the filter.

Parameters
Returns

True if the event matches the filter.

Return type

bool

fields

name of the fields.

Type

list[str]

filter_expression

compiled filter expression or None.

Type

object

filter_name

name of the filter.

Type

str

limit

row limit.

Type

int

separator

output field separator.

Type

str

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='/')[source]

Bases: object

Path filter scan tree.

CheckPath(path, path_segment_separator=None)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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

path_segments

path segments.

Type

list[str]

Module contents