plaso.lib package

Submodules

plaso.lib.bufferlib module

Circular buffer for storing event objects.

class plaso.lib.bufferlib.CircularBuffer(size)[source]

Bases: object

Class that defines a circular buffer for storing event objects.

Append(item)[source]

Add an item to the list.

Parameters:item (object) – item.
Clear()[source]

Removes all elements from the list.

Flush()[source]

Returns a generator for all items and clear the buffer.

GetCurrent()[source]

Retrieves the current item that index points to.

Returns:item.
Return type:object
__iter__()[source]

Return all elements from the list.

__len__()[source]

Return the length (the fixed size).

size

int – number of elements in the buffer.

plaso.lib.decorators module

Function decorators.

plaso.lib.decorators.deprecated(function)[source]

Decorator to mark functions or methods as deprecated.

plaso.lib.definitions module

The definitions.

plaso.lib.errors module

This file contains the error classes.

exception plaso.lib.errors.BadConfigObject[source]

Bases: plaso.lib.errors.Error

Raised when the configuration object is of the wrong type.

exception plaso.lib.errors.BadConfigOption[source]

Bases: plaso.lib.errors.Error

Raised when a faulty configuration option is encountered.

exception plaso.lib.errors.ConnectionError[source]

Bases: plaso.lib.errors.Error

Class that defines errors encountered connecting to a service.

exception plaso.lib.errors.Error[source]

Bases: Exception

Base error class.

exception plaso.lib.errors.InvalidEvent[source]

Bases: plaso.lib.errors.Error

Error indicating an event is malformed.

exception plaso.lib.errors.InvalidFilter[source]

Bases: plaso.lib.errors.Error

Error indicating an invalid filter was specified.

exception plaso.lib.errors.MalformedPresetError[source]

Bases: plaso.lib.errors.Error

Raised when a parser preset definition is malformed.

exception plaso.lib.errors.MalformedQueryError[source]

Bases: plaso.lib.errors.Error

Raised when an objectfilter query is malformed.

exception plaso.lib.errors.MaximumRecursionDepth[source]

Bases: plaso.lib.errors.Error

Raised when the maximum recursion depth is reached.

exception plaso.lib.errors.NoFormatterFound[source]

Bases: plaso.lib.errors.Error

Raised when no formatter is found for a particular event object.

exception plaso.lib.errors.ParseError[source]

Bases: plaso.lib.errors.Error

Raised when a parse error occurred.

exception plaso.lib.errors.PreProcessFail[source]

Bases: plaso.lib.errors.Error

Raised when a preprocess module is unable to gather information.

exception plaso.lib.errors.QueueAlreadyClosed[source]

Bases: plaso.lib.errors.Error

Raised when an attempt is made to close a queue that is already closed.

exception plaso.lib.errors.QueueAlreadyStarted[source]

Bases: plaso.lib.errors.Error

Raised when an attempt is made to start queue that is already started.

exception plaso.lib.errors.QueueClose[source]

Bases: plaso.lib.errors.Error

Class that implements a queue close exception.

exception plaso.lib.errors.QueueEmpty[source]

Bases: plaso.lib.errors.Error

Class that implements a queue empty exception.

exception plaso.lib.errors.QueueFull[source]

Bases: plaso.lib.errors.Error

Class that implements a queue full exception.

exception plaso.lib.errors.SerializationError[source]

Bases: plaso.lib.errors.Error

Class that defines serialization errors.

exception plaso.lib.errors.SourceScannerError[source]

Bases: plaso.lib.errors.Error

Class that defines source scanner errors.

exception plaso.lib.errors.TaggingFileError[source]

Bases: plaso.lib.errors.Error

Raised when the tagging file is invalid.

exception plaso.lib.errors.TimestampError[source]

Bases: plaso.lib.errors.Error

Class that defines timestamp errors.

exception plaso.lib.errors.UnableToLoadRegistryHelper[source]

Bases: plaso.lib.errors.Error

Raised when unable to load a Registry helper object.

exception plaso.lib.errors.UnableToParseFile[source]

Bases: plaso.lib.errors.Error

Raised when a parser is not designed to parse a file.

exception plaso.lib.errors.UserAbort[source]

Bases: plaso.lib.errors.Error

Class that defines an user initiated abort exception.

exception plaso.lib.errors.WrongBencodePlugin[source]

Bases: plaso.lib.errors.Error

Error reporting wrong bencode plugin used.

exception plaso.lib.errors.WrongCompoundZIPPlugin[source]

Bases: plaso.lib.errors.Error

Error reporting wrong compound ZIP plugin used.

exception plaso.lib.errors.WrongFormatter[source]

Bases: plaso.lib.errors.Error

Raised when the formatter is not applicable for a particular event.

exception plaso.lib.errors.WrongPlistPlugin[source]

Bases: plaso.lib.errors.Error

Error reporting wrong plist plugin used.

exception plaso.lib.errors.WrongPlugin[source]

Bases: plaso.lib.errors.Error

Raised when the plugin is of the wrong type.

exception plaso.lib.errors.WrongQueueType[source]

Bases: plaso.lib.errors.Error

Raised when an unsupported operation is attempted on a queue.

For example, attempting to Pop from a Push-only queue.

plaso.lib.lexer module

An LL(1) lexer. This lexer is very tolerant of errors and can resync.

This lexer is originally copied from the GRR project: https://code.google.com/p/grr

class plaso.lib.lexer.BinaryExpression(operator='', part=None)[source]

Bases: plaso.lib.lexer.Expression

An expression which takes two other expressions.

AddOperands(lhs, rhs)[source]

Add an operand.

Compile(filter_implementation)[source]

Compile the binary expression into a filter object.

PrintTree(depth='')[source]

Print the tree.

__str__()[source]

Return a string representation of the binary expression.

class plaso.lib.lexer.Expression[source]

Bases: object

A class representing an expression.

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.
Raises:ParseError – If there are too many arguments.
Compile(unused_filter_implementation)[source]

Given a filter implementation, compile this expression.

PrintTree(depth='')[source]

Print the tree.

SetAttribute(attribute)[source]

Set the attribute.

SetOperator(operator)[source]

Set the operator.

__str__()[source]

Return a string representation of the expression.

args = None
attribute = None
number_of_args = 1
operator = None
class plaso.lib.lexer.IdentityExpression[source]

Bases: plaso.lib.lexer.Expression

An Expression which always evaluates to True.

Compile(filter_implementation)[source]

Compile the expression.

class plaso.lib.lexer.Lexer(data='')[source]

Bases: object

A generic feed lexer.

Close()[source]

A convenience function to force us to parse all the data.

Default(**kwarg)[source]

The default callback handler.

Empty()[source]

Returns a boolean indicating if the buffer is empty.

Error(message=None, weight=1)[source]

Log an error down.

Parameters:
  • message – optional error message.
  • weight – optional error weight.
Feed(data)[source]

Feed the buffer with data.

Parameters:data – data to be processed by the lexer.
NextToken()[source]

Fetch the next token by trying to match any of the regexes in order.

PopState(**unused_kwargs)[source]

Pop the previous state from the stack.

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

Push the match back on the stream.

Parameters:string – optional data.
PushState(**unused_kwargs)[source]

Push the current state on the state stack.

tokens = []
class plaso.lib.lexer.SearchParser(data)[source]

Bases: plaso.lib.lexer.Lexer

This parser can parse the mini query language and build an AST.

Examples of valid syntax:
filename contains “foo” and (size > 100k or date before “2011-10”) date between 2011 and 2010 files older than 1 year
BinaryOperator(string=None, **unused_kwargs)[source]

Set the binary operator.

BracketClose(**unused_kwargs)[source]

Close the bracket.

BracketOpen(**unused_kwargs)[source]

Define an open bracket.

Error(message=None, unused_weight=1)[source]

Raise an error message.

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

Insert an argument to the current expression.

Parse()[source]

Parse.

Reduce()[source]

Reduce the token stack into an AST.

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

Store the attribute.

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

Store the operator.

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

Escape backslashes found inside a string quote.

Backslashes followed by anything other than [‘“rnbt] will just be included in the string.

Parameters:
  • string – The string that matched.
  • match – the match object (instance of re.MatchObject). Where match.group(1) contains the escaped code.
StringFinish(**unused_kwargs)[source]

Finish the string operation.

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

Add to the string.

StringStart(**unused_kwargs)[source]

Initialize the string.

binary_expression_cls

alias of BinaryExpression

expression_cls

alias of Expression

tokens = [<plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>]
class plaso.lib.lexer.SelfFeederMixIn(file_object=None)[source]

Bases: plaso.lib.lexer.Lexer

This mixin is used to make a lexer which feeds itself.

Note that self.file_object must be the file object we read from.

Feed(size=512)[source]

Feed data into the buffer.

Parameters:size – optional data size to read form the file-like object.
NextToken()[source]

Retrieves the next token.

Returns:The next token (instance of Token) or None.
class plaso.lib.lexer.Token(state_regex, regex, actions, next_state, flags=<RegexFlag.IGNORECASE: 2>)[source]

Bases: object

A token action.

plaso.lib.line_reader_file module

Binary line reader file-like object.

class plaso.lib.line_reader_file.BinaryDSVReader(binary_line_reader, delimiter)[source]

Bases: object

Basic reader for delimiter separated text files of unknown encoding.

This is used for reading data from text files where the content is unknown, or possibly using a mixed encoding.

__iter__()[source]

Iterates over delimiter separates values.

Yields:list(bytes) – lines of encoded bytes.
class plaso.lib.line_reader_file.BinaryLineReader(file_object, end_of_line=b'n')[source]

Bases: object

Line reader for binary file-like objects.

end_of_line

bytes – byte sequence that separates lines from each other.

MAXIMUM_READ_BUFFER_SIZE = 16777216
__enter__()[source]

Enters a with statement.

__exit__(exception_type, value, traceback)[source]

Exits a with statement.

__iter__()[source]

Returns a line of text.

Yields:bytes – line of text.
readline(size=None)[source]

Reads a single line of text.

The functions reads one entire line from the file-like object. A trailing end-of-line indicator (newline by default) is kept in the byte string (but may be absent when a file ends with an incomplete line). An empty byte string is returned only when end-of-file is encountered immediately.

Parameters:size (Optional[int]) – maximum byte size to read. If present and non-negative, it is a maximum byte count (including the trailing end-of-line) and an incomplete line may be returned.
Returns:line of text.
Return type:bytes
Raises:ValueError – if the specified size is less than zero or greater than the maximum size allowed.
readlines(sizehint=None)[source]

Reads lines of text.

The function reads until EOF using readline() and return a list containing the lines read.

Parameters:sizehint (Optional[int]) – maximum byte size to read. If present, instead of reading up to EOF, whole lines totalling sizehint bytes are read.
Returns:lines of text.
Return type:list[bytes]
tell()[source]

Retrieves the current offset into the file-like object.

Returns:current offset into the file-like object.
Return type:int

plaso.lib.loggers module

Logging related classes and functions.

class plaso.lib.loggers.CompressedFileHandler(filename, mode='a', encoding='utf-8')[source]

Bases: logging.FileHandler

Compressed file handler for logging.

plaso.lib.loggers.ConfigureLogging(debug_output=False, filename=None, mode='w', quiet_mode=False)[source]

Configures the logging root logger.

Parameters:
  • debug_output (Optional[bool]) – True if the logging should include debug output.
  • filename (Optional[str]) – log filename.
  • mode (Optional[str]) – log file access mode.
  • quiet_mode (Optional[bool]) – True if the logging should not include information output. Note that debug_output takes precedence over quiet_mode.

plaso.lib.objectfilter module

Classes to perform filtering of objects based on their data members.

Given a list of objects and a textual filter expression, these classes allow you to determine which objects match the filter. The system has two main pieces: A parser for the supported grammar and a filter implementation.

Given any complying user-supplied grammar, it is parsed with a custom lexer based on GRR’s lexer and then compiled into an actual implementation by using the filter implementation. A filter implementation simply provides actual implementations for the primitives required to perform filtering. The compiled result is always a class supporting the Filter interface.

If we define a class called Car such as:

class Car(object):
def __init__(self, code, color=”white”, doors=3):
self.code = code self.color = color self.doors = 3

And we have two instances:

ford_ka = Car(“FORDKA1”, color=”grey”) toyota_corolla = Car(“COROLLA1”, color=”white”, doors=5) fleet = [ford_ka, toyota_corolla]

We want to find cars that are grey and have 3 or more doors. We could filter our fleet like this:

criteria = “(color is grey) and (doors >= 3)” parser = ContextFilterParser(criteria).Parse() compiled_filter = parser.Compile(LowercaseAttributeFilterImp)

for car in fleet:
if compiled_filter.Matches(car):
print(“Car %s matches the supplied filter.” % car.code)
The filter expression contains two subexpressions joined by an AND operator:
“color is grey” and “doors >= 3”

This means we want to search for objects matching these two subexpressions. Let’s analyze the first one in depth “color is grey”:

“color”: the left operand specifies a search path to look for the data. This tells our filtering system to look for the color property on passed objects. “is”: the operator. Values retrieved for the “color” property will be checked against the right operand to see if they are equal. “grey”: the right operand. It specifies an explicit value to check for.

So each time an object is passed through the filter, it will expand the value of the color data member, and compare its value against “grey”.

Because data members of objects are often not simple datatypes but other objects, the system allows you to reference data members within other data members by separating each by a dot. Let’s see an example:

Let’s add a more complex Car class with default tyre data:

class CarWithTyres(Car):
def __init__(self, code, tyres=None, color=”white”, doors=3):
super(self, CarWithTyres).__init__(code, color, doors) tyres = tyres or Tyre(“Pirelli”, “PZERO”)
class Tyre(object):
def __init__(self, brand, code):
self.brand = brand self.code = code
And two new instances:
ford_ka = CarWithTyres(“FORDKA”, color=”grey”, tyres=Tyre(“AVON”, “ZT5”)) toyota_corolla = Car(“COROLLA1”, color=”white”, doors=5) fleet = [ford_ka, toyota_corolla]

To filter a car based on the tyre brand, we would use a search path of “tyres.brand”.

Because the filter implementation provides the actual classes that perform handling of the search paths, operators, etc. customizing the behavior of the filter is easy. Three basic filter implementations are given:

BaseFilterImplementation: search path expansion is done on attribute names as provided (case-sensitive). LowercaseAttributeFilterImp: search path expansion is done on the lowercased attribute name, so that it only accesses attributes, not methods. DictFilterImplementation: search path expansion is done on dictionary access to the given object. So “a.b” expands the object obj to obj[“a”][“b”]
class plaso.lib.objectfilter.AndFilter(arguments=None, value_expander=None)[source]

Bases: plaso.lib.objectfilter.Filter

Performs a boolean AND of the given Filter instances as arguments.

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

Matches(obj)[source]

Whether object obj matches this filter.

class plaso.lib.objectfilter.AttributeValueExpander[source]

Bases: plaso.lib.objectfilter.ValueExpander

An expander that gives values based on object attribute names.

class plaso.lib.objectfilter.BaseFilterImplementation[source]

Bases: object

Defines the base implementation of an object filter by its attributes.

Inherit from this class, switch any of the needed operators and pass it to the Compile method of a parsed string to obtain an executable filter.

FILTERS = {'AndFilter': <class 'plaso.lib.objectfilter.AndFilter'>, 'Context': <class 'plaso.lib.objectfilter.Context'>, 'IdentityFilter': <class 'plaso.lib.objectfilter.IdentityFilter'>, 'OrFilter': <class 'plaso.lib.objectfilter.OrFilter'>, 'ValueExpander': <class 'plaso.lib.objectfilter.AttributeValueExpander'>}
OPS = {'!=': <class 'plaso.lib.objectfilter.NotEquals'>, '<': <class 'plaso.lib.objectfilter.Less'>, '<=': <class 'plaso.lib.objectfilter.LessEqual'>, '==': <class 'plaso.lib.objectfilter.Equals'>, '>': <class 'plaso.lib.objectfilter.Greater'>, '>=': <class 'plaso.lib.objectfilter.GreaterEqual'>, 'contains': <class 'plaso.lib.objectfilter.Contains'>, 'equals': <class 'plaso.lib.objectfilter.Equals'>, 'inset': <class 'plaso.lib.objectfilter.InSet'>, 'iregexp': <class 'plaso.lib.objectfilter.RegexpInsensitive'>, 'is': <class 'plaso.lib.objectfilter.Equals'>, 'regexp': <class 'plaso.lib.objectfilter.Regexp'>}
class plaso.lib.objectfilter.BasicExpression[source]

Bases: plaso.lib.lexer.Expression

Basic Expression.

Compile(filter_implementation)[source]

Given a filter implementation, compile this expression.

FlipBool()[source]
class plaso.lib.objectfilter.BinaryExpression(operator='', part=None)[source]

Bases: plaso.lib.lexer.BinaryExpression

Compile(filter_implementation)[source]

Compile the binary expression into a filter object.

class plaso.lib.objectfilter.BinaryOperator(arguments=None, **kwargs)[source]

Bases: plaso.lib.objectfilter.Operator

Base class for binary operators.

The left operand is always a path into the object which will be expanded for values. The right operand is a value defined at initialization and is stored at self.right_operand.

class plaso.lib.objectfilter.Contains(**kwargs)[source]

Bases: plaso.lib.objectfilter.GenericBinaryOperator

Whether the right operand is contained in the value.

Operation(x, y)[source]

Performs the operation between two values.

class plaso.lib.objectfilter.Context(arguments=None, **kwargs)[source]

Bases: plaso.lib.objectfilter.Operator

Restricts the child operators to a specific context within the object.

Solves the context problem. The context problem is the following: Suppose you store a list of loaded DLLs within a process. Suppose that for each of these DLLs you store the number of imported functions and each of the imported functions name.

Imagine that a malicious DLL is injected into processes and its indicators are that it only imports one function and that it is RegQueryValueEx. Yo’d write your indicator like this:

AndOperator(
Equal(“ImportedDLLs.ImpFunctions.Name”, “RegQueryValueEx”), Equal(“ImportedDLLs.NumImpFunctions”, “1”) )

Now imagine you have these two processes on a given system.

Process1 * __ImportedDlls

  • __Name: “notevil.dll”
    • __ImpFunctions
      • __Name: “CreateFileA”
    • __NumImpFunctions: 1
  • __Name: “alsonotevil.dll”
    • __ImpFunctions
      • __Name: “RegQueryValueEx”
      • __Name: “CreateFileA”
    • __NumImpFunctions: 2

Process2 * __ImportedDlls

  • __Name: “evil.dll”
    • __ImpFunctions
      • __Name: “RegQueryValueEx”
    • __NumImpFunctions: 1

Both Process1 and Process2 match your query, as each of the indicators are evaluated separately. While you wanted to express “find me processes that have a DLL that has both one imported function and ReqQueryValueEx is in the list of imported functions”, your indicator actually means “find processes that have at least a DLL with 1 imported functions and at least one DLL that imports the ReqQueryValueEx function”.

To write such an indicator you need to specify a context of ImportedDLLs for these two clauses. Such that you convert your indicator to:

Context("ImportedDLLs",
        AndOperator(
          Equal("ImpFunctions.Name", "RegQueryValueEx"),
          Equal("NumImpFunctions", "1")
        ))

Context will execute the filter specified as the second parameter for each of the objects under “ImportedDLLs”, thus applying the condition per DLL, not per object and returning the right result.

Matches(obj)[source]

Whether object obj matches this filter.

class plaso.lib.objectfilter.ContextExpression(attribute='', part=None)[source]

Bases: plaso.lib.lexer.Expression

Represents the context operator.

Compile(filter_implementation)[source]

Compile the expression.

SetExpression(expression)[source]

Set the expression.

class plaso.lib.objectfilter.DictValueExpander[source]

Bases: plaso.lib.objectfilter.ValueExpander

An expander that gets values from dictionary access to the object.

class plaso.lib.objectfilter.Equals(**kwargs)[source]

Bases: plaso.lib.objectfilter.GenericBinaryOperator

Matches objects when the right operand equals the expanded value.

Operation(x, y)[source]

Performs the operation between two values.

class plaso.lib.objectfilter.Filter(arguments=None, value_expander=None)[source]

Bases: object

Base class for every filter.

Filter(objects)[source]

Returns a list of objects that pass the filter.

Matches(obj)[source]

Whether object obj matches this filter.

class plaso.lib.objectfilter.GenericBinaryOperator(**kwargs)[source]

Bases: plaso.lib.objectfilter.BinaryOperator

Allows easy implementations of operators.

FlipBool()[source]
Matches(obj)[source]

Whether object obj matches this filter.

Operate(values)[source]

Takes a list of values and if at least one matches, returns True.

Operation(x, y)[source]

Performs the operation between two values.

plaso.lib.objectfilter.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.lib.objectfilter.Greater(**kwargs)[source]

Bases: plaso.lib.objectfilter.GenericBinaryOperator

Whether the expanded value > right_operand.

Operation(x, y)[source]

Performs the operation between two values.

class plaso.lib.objectfilter.GreaterEqual(**kwargs)[source]

Bases: plaso.lib.objectfilter.GenericBinaryOperator

Whether the expanded value >= right_operand.

Operation(x, y)[source]

Performs the operation between two values.

class plaso.lib.objectfilter.IdentityFilter(arguments=None, value_expander=None)[source]

Bases: plaso.lib.objectfilter.Operator

Matches(_)[source]

Whether object obj matches this filter.

class plaso.lib.objectfilter.InSet(**kwargs)[source]

Bases: plaso.lib.objectfilter.GenericBinaryOperator

Whether all values are contained within the right operand.

Operation(x, y)[source]

Whether x is fully contained in y.

exception plaso.lib.objectfilter.InvalidNumberOfOperands[source]

Bases: plaso.lib.errors.Error

The number of operands provided to this operator is wrong.

class plaso.lib.objectfilter.Less(**kwargs)[source]

Bases: plaso.lib.objectfilter.GenericBinaryOperator

Whether the expanded value >= right_operand.

Operation(x, y)[source]

Performs the operation between two values.

class plaso.lib.objectfilter.LessEqual(**kwargs)[source]

Bases: plaso.lib.objectfilter.GenericBinaryOperator

Whether the expanded value <= right_operand.

Operation(x, y)[source]

Performs the operation between two values.

class plaso.lib.objectfilter.LowercaseAttributeValueExpander[source]

Bases: plaso.lib.objectfilter.AttributeValueExpander

An expander that lowercases all attribute names before access.

class plaso.lib.objectfilter.NotEquals(**kwargs)[source]

Bases: plaso.lib.objectfilter.Equals

Matches when the right operand isn’t equal to the expanded value.

class plaso.lib.objectfilter.Operator(arguments=None, value_expander=None)[source]

Bases: plaso.lib.objectfilter.Filter

Base class for all operators.

class plaso.lib.objectfilter.OrFilter(arguments=None, value_expander=None)[source]

Bases: plaso.lib.objectfilter.Filter

Performs a boolean OR of the given Filter instances as arguments.

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

Matches(obj)[source]

Whether object obj matches this filter.

class plaso.lib.objectfilter.Parser(data)[source]

Bases: plaso.lib.lexer.SearchParser

Parses and generates an AST for a query written in the described language.

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”)
ContextOperator(string='', **unused_kwargs)[source]
Error(message=None, _=None)[source]

Raise an error message.

FlipAllowed()[source]

Raise an error if the not keyword is used where it is not allowed.

FlipLogic(**unused_kwargs)[source]

Flip the boolean logic of the expression.

If an expression is configured to return True when the condition is met this logic will flip that to False, and vice versa.

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

Converts a hex escaped string.

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

Insert an argument to the current expression.

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

Inserts a Float argument.

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

Inserts an Integer in base16 argument.

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

Inserts an Integer argument.

Reduce()[source]

Reduce the token stack into an AST.

StoreAttribute(string='', **kwargs)[source]

Store the attribute.

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

Escape backslashes found inside a string quote.

Backslashes followed by anything other than [‘“rnbt.ws] will raise an Error.

Parameters:
  • string – The string that matched.
  • match – the match object (instance of re.MatchObject). Where match.group(1) contains the escaped code.
Raises:

ParseError – When the escaped string is not one of [‘“rnbt]

StringFinish(**unused_kwargs)[source]

Finish the string operation.

binary_expression_cls

alias of BinaryExpression

context_cls

alias of ContextExpression

expression_cls

alias of BasicExpression

tokens = [<plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>, <plaso.lib.lexer.Token object>]
class plaso.lib.objectfilter.Regexp(*children, **kwargs)[source]

Bases: plaso.lib.objectfilter.GenericBinaryOperator

Whether the value matches the regexp in the right operand.

Operation(x, unused_y)[source]

Performs the operation between two values.

class plaso.lib.objectfilter.RegexpInsensitive(*children, **kwargs)[source]

Bases: plaso.lib.objectfilter.Regexp

Whether the value matches the regexp in the right operand.

class plaso.lib.objectfilter.UnaryOperator(operand, **kwargs)[source]

Bases: plaso.lib.objectfilter.Operator

Base class for unary operators.

class plaso.lib.objectfilter.ValueExpander[source]

Bases: object

Encapsulates the logic to expand values available in an object.

Once instantiated and called, this class returns all the values that follow a given field path.

Expand(obj, path)[source]

Returns a list of all the values for the given path in the object obj.

Given a path such as [“sub1”, “sub2”] it returns all the values available in obj.sub1.sub2 as a list. sub1 and sub2 must be data attributes or properties.

If sub1 returns a list of objects, or a generator, Expand aggregates the values for the remaining path for each of the objects, thus returning a list of all the values under the given path for the input object.

Parameters:
  • obj – An object that will be traversed for the given path
  • path – A list of strings
Yields:

The values once the object is traversed.

FIELD_SEPARATOR = '.'

plaso.lib.pfilter module

An extension of the objectfilter to provide plaso specific options.

class plaso.lib.pfilter.BaseParser(data)[source]

Bases: plaso.lib.objectfilter.Parser

Plaso version of the Parser.

expression_cls

alias of PlasoExpression

class plaso.lib.pfilter.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.

__eq__(x)[source]

Check if equal.

__ge__(x)[source]

Greater or equal comparison.

__gt__(x)[source]

Greater comparison.

__le__(x)[source]

Less or equal comparison.

__lt__(x)[source]

Less comparison

__ne__(x)[source]

Check if not equal.

__str__()[source]

Return a string representation of the object.

class plaso.lib.pfilter.DictObject(dict_object)[source]

Bases: object

A simple object representing a dict object.

To filter against an object that is stored as a dictionary the dict is converted into a simple object. Since keys can contain spaces and/or other symbols they are stripped out to make filtering work like it is another object.

Example dict:

{'A value': 234,
 'this (my) key_': 'value',
 'random': True,
}

This object would then allow access to object.thismykey that would access the key ‘this (my) key_’ inside the dict.

__getattr__(attr)[source]

Return back entries from the dictionary.

class plaso.lib.pfilter.PlasoAttributeFilterImplementation[source]

Bases: plaso.lib.objectfilter.BaseFilterImplementation

Does field name access on the lowercase version of names.

Useful to only access attributes and properties with Google’s python naming style.

FILTERS = {'AndFilter': <class 'plaso.lib.objectfilter.AndFilter'>, 'Context': <class 'plaso.lib.objectfilter.Context'>, 'IdentityFilter': <class 'plaso.lib.objectfilter.IdentityFilter'>, 'OrFilter': <class 'plaso.lib.objectfilter.OrFilter'>, 'ValueExpander': <class 'plaso.lib.pfilter.PlasoValueExpander'>}
OPS = {'!=': <class 'plaso.lib.objectfilter.NotEquals'>, '<': <class 'plaso.lib.objectfilter.Less'>, '<=': <class 'plaso.lib.objectfilter.LessEqual'>, '==': <class 'plaso.lib.objectfilter.Equals'>, '>': <class 'plaso.lib.objectfilter.Greater'>, '>=': <class 'plaso.lib.objectfilter.GreaterEqual'>, 'contains': <class 'plaso.lib.objectfilter.Contains'>, 'equals': <class 'plaso.lib.objectfilter.Equals'>, 'inset': <class 'plaso.lib.objectfilter.InSet'>, 'iregexp': <class 'plaso.lib.objectfilter.RegexpInsensitive'>, 'is': <class 'plaso.lib.objectfilter.Equals'>, 'regexp': <class 'plaso.lib.objectfilter.Regexp'>}
class plaso.lib.pfilter.PlasoExpression[source]

Bases: plaso.lib.objectfilter.BasicExpression

A Plaso specific expression.

Compile(filter_implementation)[source]

Compiles the filter implementation.

Parameters:filter_implementation – a filter object (instance of objectfilter.TODO).
Returns:A filter operator (instance of TODO).
Raises:ParserError – if an unknown operator is provided.
swap_source = {'date': 'timestamp', 'datetime': 'timestamp', 'description': 'message', 'description_long': 'message', 'description_short': 'message_short', 'time': 'timestamp'}
class plaso.lib.pfilter.PlasoValueExpander[source]

Bases: plaso.lib.objectfilter.AttributeValueExpander

An expander that gives values based on object attribute names.

class plaso.lib.pfilter.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.lib.plist module

The plist file object.

class plaso.lib.plist.PlistFile[source]

Bases: object

Class that defines a plist file.

root_key

dict – the plist root key.

GetValueByPath(path_segments)[source]

Retrieves a plist value by path.

Parameters:path_segments (list[str]) – path segment strings relative to the root of the plist.
Returns:The value of the key specified by the path or None.
Return type:object
Read(file_object)[source]

Reads a plist from a file-like object.

Parameters:

file_object (dfvfs.FileIO) – a file-like object containing plist data.

Raises:
  • IOError – if the plist file-like object cannot be read.
  • OSError – if the plist file-like object cannot be read.

plaso.lib.py2to3 module

The Python 2 and 3 compatible type definitions.

plaso.lib.specification module

The format specification classes.

class plaso.lib.specification.FormatSpecification(identifier, text_format=False)[source]

Bases: object

The format specification.

AddNewSignature(pattern, offset=None)[source]

Adds a signature.

Parameters:
  • pattern (bytes) – pattern of the signature.
  • offset (int) – offset of the signature. None is used to indicate the signature has no offset. A positive offset is relative from the start of the data a negative offset is relative from the end of the data.
IsTextFormat()[source]

Determines if the format is a text format.

Returns:True if the format is a text format, False otherwise.
Return type:bool
class plaso.lib.specification.FormatSpecificationStore[source]

Bases: object

The store for format specifications.

AddNewSpecification(identifier)[source]

Adds a new format specification.

Parameters:identifier (str) – format identifier, which should be unique for the store.
Returns:format specification.
Return type:FormatSpecification
Raises:KeyError – if the store already contains a specification with the same identifier.
AddSpecification(specification)[source]

Adds a format specification.

Parameters:specification (FormatSpecification) – format specification.
Raises:KeyError – if the store already contains a specification with the same identifier.
GetSpecificationBySignature(signature_identifier)[source]

Retrieves a specification mapped to a signature identifier.

Parameters:signature_identifier (str) – unique signature identifier for a specification store.
Returns:
format specification or None if the signature
identifier does not exist within the specification store.
Return type:FormatSpecification
specifications

iterator – specifications iterator.

class plaso.lib.specification.Signature(pattern, offset=None)[source]

Bases: object

The format specification signature.

The signature consists of a byte string pattern, an optional offset relative to the start of the data, and a value to indicate if the pattern is bound to the offset.

SetIdentifier(identifier)[source]

Sets the identifier of the signature in the specification store.

Parameters:identifier (str) – unique signature identifier for a specification store.

plaso.lib.timelib module

Time manipulation functions and variables.

This module contain common methods that can be used to convert timestamps from various formats into number of micro seconds since January 1, 1970, 00:00:00 UTC that is used internally to store timestamps.

It also contains various functions to represent timestamps in a more human readable form.

plaso.lib.timelib.GetCurrentYear()[source]

Determines the current year.

plaso.lib.timelib.GetYearFromPosixTime(posix_time, timezone=<Mock id='139838258168832'>)[source]

Gets the year from a POSIX timestamp

The POSIX time is the number of seconds since 1970-01-01 00:00:00 UTC.

Parameters:
  • posix_time – An integer containing the number of seconds since 1970-01-01 00:00:00 UTC.
  • timezone – Optional timezone of the POSIX timestamp.
Returns:

The year of the POSIX timestamp.

Raises:

ValueError – If the posix timestamp is out of the range of supported values.

class plaso.lib.timelib.Timestamp[source]

Bases: object

Class for converting timestamps to Plaso timestamps.

The Plaso timestamp is a 64-bit signed timestamp value containing: micro seconds since 1970-01-01 00:00:00.

The timestamp is not necessarily in UTC.

classmethod CopyFromString(time_string)[source]

Copies a timestamp from a string containing a date and time value.

Parameters:time_string – A string containing a date and time value 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.
Returns:The timestamp which is an integer containing the number of micro seconds since January 1, 1970, 00:00:00 UTC.
Raises:ValueError – if the time string is invalid or not supported.
classmethod CopyToDatetime(timestamp, timezone, raise_error=False)[source]

Copies the timestamp to a datetime object.

Parameters:
  • timestamp – The timestamp which is an integer containing the number of micro seconds since January 1, 1970, 00:00:00 UTC.
  • timezone – The timezone (pytz.timezone) object.
  • raise_error – Boolean that if set to True will not absorb an OverflowError if the timestamp is out of bounds. By default there will be no error raised.
Returns:

A datetime object (instance of datetime.datetime). A datetime object of January 1, 1970 00:00:00 UTC is returned on error if raises_error is not set.

Raises:
  • OverflowError – If raises_error is set to True and an overflow error occurs.
  • ValueError – If raises_error is set to True and no timestamp value is provided.
classmethod CopyToIsoFormat(timestamp, timezone=<Mock id='139838258363360'>, raise_error=False)[source]

Copies the timestamp to an ISO 8601 formatted string.

Parameters:
  • timestamp – The timestamp which is an integer containing the number of micro seconds since January 1, 1970, 00:00:00 UTC.
  • timezone – Optional timezone (instance of pytz.timezone).
  • raise_error – Boolean that if set to True will not absorb an OverflowError if the timestamp is out of bounds. By default there will be no error raised.
Returns:

A string containing an ISO 8601 formatted date and time.

classmethod FromTimeString(time_string, dayfirst=False, gmt_as_timezone=True, timezone=<Mock id='139838258168496'>)[source]

Converts a string containing a date and time value into a timestamp.

Parameters:
  • time_string – String that contains a date and time value.
  • dayfirst – An optional boolean argument. If set to true then the parser will change the precedence in which it parses timestamps from MM-DD-YYYY to DD-MM-YYYY (and YYYY-MM-DD will be YYYY-DD-MM, etc).
  • gmt_as_timezone – Sometimes the dateutil parser will interpret GMT and UTC the same way, that is not make a distinction. By default this is set to true, that is GMT can be interpreted differently than UTC. If that is not the expected result this attribute can be set to false.
  • timezone – Optional timezone object (instance of pytz.timezone) that the data and time value in the string represents. This value is used when the timezone cannot be determined from the string.
Returns:

The timestamp which is an integer containing the number of micro seconds since January 1, 1970, 00:00:00 UTC or 0 on error.

Raises:

TimestampError – if the time string could not be parsed.

classmethod GetNow()[source]

Retrieves the current time (now) as a timestamp in UTC.

Returns:The timestamp which is an integer containing the number of micro seconds since January 1, 1970, 00:00:00 UTC.
classmethod LocaltimeToUTC(timestamp, timezone, is_dst=False)[source]

Converts the timestamp in localtime of the timezone to UTC.

Parameters:
  • timestamp – The timestamp which is an integer containing the number of micro seconds since January 1, 1970, 00:00:00 UTC.
  • timezone – The timezone (pytz.timezone) object.
  • is_dst – A boolean to indicate the timestamp is corrected for daylight savings time (DST) only used for the DST transition period.
Returns:

The timestamp which is an integer containing the number of micro seconds since January 1, 1970, 00:00:00 UTC or 0 on error.

NONE_TIMESTAMP = 0
classmethod RoundToSeconds(timestamp)[source]

Takes a timestamp value and rounds it to a second precision.

Module contents