plaso.lib package

Submodules

plaso.lib.bufferlib module

Circular buffer for storing event objects.

class plaso.lib.bufferlib.CircularBuffer(size)

Bases: object

Class that defines a circular buffer for storing event objects.

Append(item)

Add an item to the list.

Parameters

item (object) – item.

Clear()

Removes all elements from the list.

Flush()

Returns a generator for all items and clear the buffer.

GetCurrent()

Retrieves the current item that index points to.

Returns

item.

Return type

object

__iter__()

Return all elements from the list.

__len__()

Return the length (the fixed size).

size

number of elements in the buffer.

Type

int

plaso.lib.decorators module

Function decorators.

plaso.lib.decorators.deprecated(function)

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

Bases: plaso.lib.errors.Error

Raised when the configuration object is of the wrong type.

exception plaso.lib.errors.BadConfigOption

Bases: plaso.lib.errors.Error

Raised when a faulty configuration option is encountered.

exception plaso.lib.errors.ConnectionError

Bases: plaso.lib.errors.Error

Error connecting to a service.

exception plaso.lib.errors.Error

Bases: Exception

Base error class.

exception plaso.lib.errors.InvalidEvent

Bases: plaso.lib.errors.Error

Error indicating an event is malformed.

exception plaso.lib.errors.InvalidFilter

Bases: plaso.lib.errors.Error

Error indicating an invalid filter was specified.

exception plaso.lib.errors.InvalidNumberOfOperands

Bases: plaso.lib.errors.Error

The number of operands provided to an objectfilter operator is wrong.

exception plaso.lib.errors.MalformedPresetError

Bases: plaso.lib.errors.Error

Raised when a parser preset definition is malformed.

exception plaso.lib.errors.MaximumRecursionDepth

Bases: plaso.lib.errors.Error

Raised when the maximum recursion depth is reached.

exception plaso.lib.errors.NoFormatterFound

Bases: plaso.lib.errors.Error

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

exception plaso.lib.errors.ParseError

Bases: plaso.lib.errors.Error

Raised when a parse error occurred.

exception plaso.lib.errors.PreProcessFail

Bases: plaso.lib.errors.Error

Raised when a preprocess module is unable to gather information.

exception plaso.lib.errors.QueueAlreadyClosed

Bases: plaso.lib.errors.Error

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

exception plaso.lib.errors.QueueAlreadyStarted

Bases: plaso.lib.errors.Error

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

exception plaso.lib.errors.QueueClose

Bases: plaso.lib.errors.Error

Class that implements a queue close exception.

exception plaso.lib.errors.QueueEmpty

Bases: plaso.lib.errors.Error

Class that implements a queue empty exception.

exception plaso.lib.errors.QueueFull

Bases: plaso.lib.errors.Error

Class that implements a queue full exception.

exception plaso.lib.errors.SerializationError

Bases: plaso.lib.errors.Error

Class that defines serialization errors.

exception plaso.lib.errors.SourceScannerError

Bases: plaso.lib.errors.Error

Class that defines source scanner errors.

exception plaso.lib.errors.TaggingFileError

Bases: plaso.lib.errors.Error

Raised when the tagging file is invalid.

exception plaso.lib.errors.TimestampError

Bases: plaso.lib.errors.Error

Class that defines timestamp errors.

exception plaso.lib.errors.UnableToLoadRegistryHelper

Bases: plaso.lib.errors.Error

Raised when unable to load a Registry helper object.

exception plaso.lib.errors.UnableToParseFile

Bases: plaso.lib.errors.Error

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

exception plaso.lib.errors.UserAbort

Bases: plaso.lib.errors.Error

Class that defines an user initiated abort exception.

exception plaso.lib.errors.WrongBencodePlugin

Bases: plaso.lib.errors.Error

Error reporting wrong bencode plugin used.

exception plaso.lib.errors.WrongCompoundZIPPlugin

Bases: plaso.lib.errors.Error

Error reporting wrong compound ZIP plugin used.

exception plaso.lib.errors.WrongFormatter

Bases: plaso.lib.errors.Error

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

exception plaso.lib.errors.WrongPlistPlugin

Bases: plaso.lib.errors.Error

Error reporting wrong plist plugin used.

exception plaso.lib.errors.WrongPlugin

Bases: plaso.lib.errors.Error

Raised when the plugin is of the wrong type.

exception plaso.lib.errors.WrongQueueType

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.line_reader_file module

Binary line reader file-like object.

class plaso.lib.line_reader_file.BinaryDSVReader(binary_line_reader, delimiter)

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__()

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

Bases: object

Line reader for binary file-like objects.

end_of_line

byte sequence that separates lines from each other.

Type

bytes

MAXIMUM_READ_BUFFER_SIZE = 16777216

__enter__()

Enters a with statement.

__exit__(exception_type, value, traceback)

Exits a with statement.

__iter__()

Returns a line of text.

Yields

bytes – line of text.

readline(size=None)

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)

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

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

Bases: logging.FileHandler

Compressed file handler for logging.

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

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.plist module

The plist file object.

class plaso.lib.plist.PlistFile

Bases: object

Class that defines a plist file.

root_key

the plist root key.

Type

dict

GetValueByPath(path_segments)

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)

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)

Bases: object

The format specification.

AddNewSignature(pattern, offset=None)

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

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

Bases: object

The store for format specifications.

AddNewSpecification(identifier)

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)

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)

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

specifications iterator.

Type

iterator

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

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)

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 microseconds 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()

Determines the current year.

plaso.lib.timelib.GetYearFromPosixTime(posix_time, timezone=<Mock id='139720172658928'>)

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

Bases: object

Class for converting timestamps to Plaso timestamps.

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

The timestamp is not necessarily in UTC.

classmethod CopyFromString(time_string)

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

Parameters

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

timestamp which is an integer containing the number of microseconds

since January 1, 1970, 00:00:00 UTC.

Return type

int

Raises

ValueError – if the time string is invalid or not supported.

classmethod CopyToIsoFormat(timestamp, timezone=<Mock id='139720172658872'>, raise_error=False)

Copies the timestamp to an ISO 8601 formatted string.

Parameters

• timestamp (int) – a timestamp containing the number of microseconds since January 1, 1970, 00:00:00 UTC.

• timezone (Optional[pytz.timezone]) – time zone.

• raise_error (Optional[bool]) – True if an OverflowError should be raised if the timestamp is out of bounds.

Returns

date and time formatted in ISO 8601.

Return type

str

Raises

• OverflowError – if the timestamp value is out of bounds and raise_error is True.

• ValueError – if the timestamp value is missing.

classmethod FromTimeString(time_string, dayfirst=False, gmt_as_timezone=True, timezone=<Mock id='139720172660664'>)

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 microseconds since January 1, 1970, 00:00:00 UTC or 0 on error.

Raises

TimestampError – if the time string could not be parsed.

classmethod GetNow()

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

Returns

The timestamp which is an integer containing the number of microseconds since January 1, 1970, 00:00:00 UTC.

classmethod LocaltimeToUTC(timestamp, timezone, is_dst=False)

Converts the timestamp in localtime of the timezone to UTC.

Parameters

• timestamp – The timestamp which is an integer containing the number of microseconds 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 microseconds since January 1, 1970, 00:00:00 UTC or 0 on error.

NONE_TIMESTAMP = 0

classmethod RoundToSeconds(timestamp)

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

Module contents