plaso.engine package

Submodules

plaso.engine.configurations module

Processing configuration classes.

class plaso.engine.configurations.CredentialConfiguration(credential_data=None, credential_type=None, path_spec=None)

Bases: plaso.containers.interface.AttributeContainer

Configuration settings for a credential.

credential_data

bytes – credential data.

credential_type

str – credential type.

path_spec

dfvfs.PathSpec – path specification.

CONTAINER_TYPE = u'credential_configuration'

class plaso.engine.configurations.EventExtractionConfiguration

Bases: plaso.containers.interface.AttributeContainer

Configuration settings for event extraction.

These settings are primarily used by the parser mediator.

filter_object

objectfilter.Filter – filter that specifies which events to include.

text_prepend

str – text to prepend to every event.

CONTAINER_TYPE = u'event_extraction_configuration'

class plaso.engine.configurations.ExtractionConfiguration

Bases: plaso.containers.interface.AttributeContainer

Configuration settings for extraction.

These settings are primarily used by the extraction worker.

hasher_file_size_limit

int – maximum file size that hashers should process, where 0 or None represents unlimited.

hasher_names_string

str – comma separated string of names of hashers to use during processing.

process_archives

bool – True if archive files should be scanned for file entries.

process_compressed_streams

bool – True if file content in compressed streams should be processed.

yara_rules_string

str – Yara rule definitions.

CONTAINER_TYPE = u'extraction_configuration'

class plaso.engine.configurations.InputSourceConfiguration

Bases: plaso.containers.interface.AttributeContainer

Configuration settings of an input source.

mount_path

str – path of a “mounted” directory input source.

CONTAINER_TYPE = u'input_source'

class plaso.engine.configurations.ProcessingConfiguration

Bases: plaso.containers.interface.AttributeContainer

Configuration settings for processing.

credentials

list[CredentialConfiguration] – credential configurations.

data_location

str – path to the data files.

debug_output

bool – True if debug output should be enabled.

event_extraction

EventExtractionConfiguration – event extraction configuration.

extraction

ExtractionConfiguration – extraction configuration.

filter_file

str – path to a file with find specifications.

input_source

InputSourceConfiguration – input source configuration.

log_filename

str – name of the log file.

parser_filter_expression

str – parser filter expression, where None represents all parsers and plugins.

preferred_year

int – preferred initial year value for year-less date and time values.

profiling

ProfilingConfiguration – profiling configuration.

temporary_directory

str – path of the directory for temporary files.

CONTAINER_TYPE = u'processing_configuration'

class plaso.engine.configurations.ProfilingConfiguration

Bases: plaso.containers.interface.AttributeContainer

Configuration settings for profiling.

directory

str – path to the directory where the profiling sample files should be stored.

profilers

set(str) – names of the profilers to enable. Supported profilers are:

• ‘guppy’, which profiles memory usage using guppy;
• ‘memory’, which profiles memory usage;
• ‘parsers’, which profiles CPU time consumed by individual parsers;
• ‘processing’, which profiles CPU time consumed by different parts of processing;
• ‘serializers’, which profiles CPU time consumed by individual serializers.

sample_rate

int – the profiling sample rate. Contains the number of event sources processed.

CONTAINER_TYPE = u'profiling_configuration'

HaveProfileMemory()

Determines if memory profiling is configured.

Returns:True if memory profiling is configured. Return type:bool

HaveProfileMemoryGuppy()

Determines if memory profiling with guppy is configured.

Returns:True if memory profiling with guppy is configured. Return type:bool

HaveProfileParsers()

Determines if parsers profiling is configured.

Returns:True if parsers profiling is configured. Return type:bool

HaveProfileProcessing()

Determines if processing profiling is configured.

Returns:True if processing profiling is configured. Return type:bool

HaveProfileSerializers()

Determines if serializers profiling is configured.

Returns:True if serializers profiling is configured. Return type:bool

plaso.engine.engine module

plaso.engine.extractors module

plaso.engine.filter_file module

Filter file.

class plaso.engine.filter_file.FilterFile(path)

Bases: object

Filter file.

A filter file contains one or more path filters.

A path filter may contain path expansion attributes. Such an attribute is defined as anything within a curly bracket, for example “System{my_attribute}PathKeyname”. If the attribute “my_attribute” is defined its runtime value will be replaced with placeholder in the path filter such as “SystemMyValuePathKeyname”.

If the path filter needs to have curly brackets in the path then these need to be escaped with another curly bracket, for example “System{my_attribute}{{123-AF25-E523}}KeyName”, where “{{123-AF25-E523}}” will be replaced with “{123-AF25-E523}” at runtime.

BuildFindSpecs(environment_variables=None)

Build find specification from a filter file.

Parameters:environment_variables (Optional[list[EnvironmentVariableArtifact]]) – environment variables. Returns:find specification. Return type:list[dfvfs.FindSpec]

plaso.engine.knowledge_base module

The artifact knowledge base object.

The knowledge base is filled by user provided input and the pre-processing phase. It is intended to provide successive phases, like the parsing and analysis phases, with essential information like e.g. the timezone and codepage of the source data.

class plaso.engine.knowledge_base.KnowledgeBase

Bases: object

Class that implements the artifact knowledge base.

AddEnvironmentVariable(environment_variable)

Adds an environment variable.

Parameters:environment_variable (EnvironmentVariableArtifact) – environment variable artifact. Raises:KeyError – if the environment variable already exists.

AddUserAccount(user_account, session_identifier=0)

Adds an user account.

Parameters:

• user_account (UserAccountArtifact) – user account artifact.
• session_identifier (Optional[str])) – session identifier, where CURRENT_SESSION represents the active session.

Raises:

KeyError – if the user account already exists.

CURRENT_SESSION = 0

GetEnvironmentVariable(name)

Retrieves an environment variable.

Parameters:name (str) – name of the environment variable. Returns:

environment variable artifact or None

if there was no value set for the given name.

Return type:EnvironmentVariableArtifact

GetEnvironmentVariables()

Retrieves the environment variables.

Returns:environment variable artifacts. Return type:list[EnvironmentVariableArtifact]

GetHostname(session_identifier=0)

Retrieves the hostname related to the event.

If the hostname is not stored in the event it is determined based on the preprocessing information that is stored inside the storage file.

Parameters:session_identifier (Optional[str])) – session identifier, where CURRENT_SESSION represents the active session. Returns:hostname. Return type:str

GetStoredHostname()

Retrieves the stored hostname.

The hostname is determined based on the preprocessing information that is stored inside the storage file.

Returns:hostname. Return type:str

GetSystemConfigurationArtifact(session_identifier=0)

Retrieves the knowledge base as a system configuration artifact.

Parameters:session_identifier (Optional[str])) – session identifier, where CURRENT_SESSION represents the active session. Returns:system configuration artifact. Return type:SystemConfigurationArtifact

GetUsernameByIdentifier(user_identifier, session_identifier=0)

Retrieves the username based on an user identifier.

Parameters:

• user_identifier (str) – user identifier, either a UID or SID.
• session_identifier (Optional[str])) – session identifier, where CURRENT_SESSION represents the active session.

Returns:

username.

Return type:

str

GetUsernameForPath(path)

Retrieves a username for a specific path.

This is determining if a specific path is within a user’s directory and returning the username of the user if so.

Parameters:path (str) – path. Returns:

username or None if the path does not appear to be within a user’s

directory.

Return type:str

GetValue(identifier, default_value=None)

Retrieves a value by identifier.

Parameters:

• identifier (str) – case insensitive unique identifier for the value.
• default_value (object) – default value.

Returns:

value or default value if not available.

Return type:

object

Raises:

TypeError – if the identifier is not a string type.

HasUserAccounts()

Determines if the knowledge base contains user accounts.

Returns:True if the knowledge base contains user accounts. Return type:bool

ReadSystemConfigurationArtifact(system_configuration, session_identifier=0)

Reads the knowledge base values from a system configuration artifact.

Note that this overwrites existing values in the knowledge base.

Parameters:

• system_configuration (SystemConfigurationArtifact) – system configuration artifact.
• session_identifier (Optional[str])) – session identifier, where CURRENT_SESSION represents the active session.

SetCodepage(codepage)

Sets the codepage.

Parameters:codepage (str) – codepage. Raises:ValueError – if the codepage is not supported.

SetEnvironmentVariable(environment_variable)

Sets an environment variable.

Parameters:environment_variable (EnvironmentVariableArtifact) – environment variable artifact.

SetHostname(hostname, session_identifier=0)

Sets a hostname.

Parameters:

• hostname (HostnameArtifact) – hostname artifact.
• session_identifier (Optional[str])) – session identifier, where CURRENT_SESSION represents the active session.

SetTimeZone(time_zone)

Sets the time zone.

Parameters:time_zone (str) – time zone. Raises:ValueError – if the timezone is not supported.

SetValue(identifier, value)

Sets a value by identifier.

Parameters:

• identifier (str) – case insensitive unique identifier for the value.
• value (object) – value.

Raises:

TypeError – if the identifier is not a string type.

codepage

str – codepage of the current session.

hostname

str – hostname of the current session.

timezone

datetime.tzinfo – timezone of the current session.

user_accounts

list[UserAccountArtifact] – user accounts of the current session.

year

int – year of the current session.

plaso.engine.path_helper module

The path helper.

class plaso.engine.path_helper.PathHelper

Bases: object

Class that implements the path helper.

classmethod ExpandWindowsPath(path, environment_variables)

Expands a Windows path containing environment variables.

Parameters:

• path (str) – Windows path with environment variables.
• environment_variables (list[EnvironmentVariableArtifact]) – environment variables.

Returns:

expanded Windows path.

Return type:

str

classmethod GetDisplayNameForPathSpec(path_spec, mount_path=None, text_prepend=None)

Retrieves the display name of a path specification.

Parameters:

• path_spec (dfvfs.PathSpec) – path specification.
• mount_path (Optional[str]) – path where the file system that is used by the path specification is mounted, such as “/mnt/image”. The mount path will be stripped from the absolute path defined by the path specification.
• text_prepend (Optional[str]) – text to prepend.

Returns:

human readable version of the path specification or None.

Return type:

str

classmethod GetRelativePathForPathSpec(path_spec, mount_path=None)

Retrieves the relative path of a path specification.

If a mount path is defined the path will be relative to the mount point, otherwise the path is relative to the root of the file system that is used by the path specification.

Parameters:

• path_spec (dfvfs.PathSpec) – path specification.
• mount_path (Optional[str]) – path where the file system that is used by the path specification is mounted, such as “/mnt/image”. The mount path will be stripped from the absolute path defined by the path specification.

Returns:

relative path or None.

Return type:

str

plaso.engine.plaso_queue module

Queue management implementation for Plaso.

This file contains an implementation of a queue used by plaso for queue management.

The queue has been abstracted in order to provide support for different implementations of the queueing mechanism, to support multi processing and scalability.

class plaso.engine.plaso_queue.Queue

Bases: object

Class that implements the queue interface.

Close(abort=False)

Closes the queue.

Parameters:abort (Optional[bool]) – whether the Close is the result of an abort condition. If True, queue contents may be lost.

IsEmpty()

Determines if the queue is empty.

Open()

Opens the queue, ready to enqueue or dequeue items.

PopItem()

Pops an item off the queue.

Raises:QueueEmpty – when the queue is empty.

PushItem(item, block=True)

Pushes an item onto the queue.

Parameters:

• item (object) – item to add.
• block (bool) – whether to block if the queue is full.

Raises:

QueueFull – if the queue is full, and the item could not be added.

class plaso.engine.plaso_queue.QueueAbort

Bases: object

Class that implements a queue abort.

plaso.engine.process_info module

This file contains a class to get process information.

class plaso.engine.process_info.ProcessInfo(pid)

Bases: object

Provides information about a running process.

GetUsedMemory()

Retrieves the amount of memory used by the process.

Returns:

amount of memory in bytes used by the process or None

if not available.

Return type:int

plaso.engine.processing_status module

Processing status classes.

class plaso.engine.processing_status.ProcessStatus

Bases: object

The status of an individual process.

display_name

str – human readable of the file entry currently being processed by the process.

identifier

str – process identifier.

last_running_time

int – timestamp of the last update when the process had a running process status.

number_of_consumed_errors

int – total number of errors consumed by the process.

number_of_consumed_errors_delta

int – number of errors consumed by the process since the last status update.

number_of_consumed_event_tags

int – total number of event tags consumed by the process.

number_of_consumed_event_tags_delta

int – number of event tags consumed by the process since the last status update.

number_of_consumed_events

int – total number of events consumed by the process.

number_of_consumed_events_delta

int – number of events consumed by the process since the last status update.

number_of_consumed_reports

int – total number of event reports consumed by the process.

number_of_consumed_reports_delta

int – number of event reports consumed by the process since the last status update.

number_of_consumed_sources

int – total number of event sources consumed by the process.

number_of_consumed_sources_delta

int – number of event sources consumed by the process since the last status update.

number_of_produced_errors

int – total number of errors produced by the process.

number_of_produced_errors_delta

int – number of errors produced by the process since the last status update.

number_of_produced_event_tags

int – total number of event tags produced by the process.

number_of_produced_event_tags_delta

int – number of event tags produced by the process since the last status update.

number_of_produced_events

int – total number of events produced by the process.

number_of_produced_events_delta

int – number of events produced by the process since the last status update.

number_of_produced_reports

int – total number of event reports produced by the process.

number_of_produced_reports_delta

int – number of event reports produced by the process since the last status update.

number_of_produced_sources

int – total number of event sources produced by the process.

number_of_produced_sources_delta

int – number of event sources produced by the process since the last status update.

pid

int – process identifier (PID).

status

str – human readable status indication e.g. ‘Hashing’, ‘Idle’.

used_memory

int – size of used memory in bytes.

UpdateNumberOfErrors(number_of_consumed_errors, number_of_produced_errors)

Updates the number of errors.

Parameters:

• number_of_consumed_errors (int) – total number of errors consumed by the process.
• number_of_produced_errors (int) – total number of errors produced by the process.

Returns:

True if either number of errors has increased.

Return type:

bool

Raises:

ValueError – if the consumed or produced number of errors is smaller than the value of the previous update.

UpdateNumberOfEventReports(number_of_consumed_reports, number_of_produced_reports)

Updates the number of event reports.

Parameters:

• number_of_consumed_reports (int) – total number of event reports consumed by the process.
• number_of_produced_reports (int) – total number of event reports produced by the process.

Returns:

True if either number of event reports has increased.

Return type:

bool

Raises:

ValueError – if the consumed or produced number of event reports is smaller than the value of the previous update.

UpdateNumberOfEventSources(number_of_consumed_sources, number_of_produced_sources)

Updates the number of event sources.

Parameters:

• number_of_consumed_sources (int) – total number of event sources consumed by the process.
• number_of_produced_sources (int) – total number of event sources produced by the process.

Returns:

True if either number of event sources has increased.

Return type:

bool

Raises:

ValueError – if the consumed or produced number of event sources is smaller than the value of the previous update.

UpdateNumberOfEventTags(number_of_consumed_event_tags, number_of_produced_event_tags)

Updates the number of event tags.

Parameters:

• number_of_consumed_event_tags (int) – total number of event tags consumed by the process.
• number_of_produced_event_tags (int) – total number of event tags produced by the process.

Returns:

True if either number of event tags has increased.

Return type:

bool

Raises:

ValueError – if the consumed or produced number of event tags is smaller than the value of the previous update.

UpdateNumberOfEvents(number_of_consumed_events, number_of_produced_events)

Updates the number of events.

Parameters:

• number_of_consumed_events (int) – total number of events consumed by the process.
• number_of_produced_events (int) – total number of events produced by the process.

Returns:

True if either number of events has increased.

Return type:

bool

Raises:

ValueError – if the consumed or produced number of events is smaller than the value of the previous update.

class plaso.engine.processing_status.ProcessingStatus

Bases: object

The status of the overall extraction process (processing).

aborted

bool – True if processing was aborted.

error_path_specs

list[dfvfs.PathSpec] – path specifications that caused critical errors during processing.

foreman_status

ProcessingStatus – foreman processing status.

tasks_status

TasksStatus – status information about tasks.

UpdateForemanStatus(identifier, status, pid, used_memory, display_name, number_of_consumed_sources, number_of_produced_sources, number_of_consumed_events, number_of_produced_events, number_of_consumed_event_tags, number_of_produced_event_tags, number_of_consumed_errors, number_of_produced_errors, number_of_consumed_reports, number_of_produced_reports)

Updates the status of the foreman.

Parameters:

• identifier (str) – foreman identifier.
• status (str) – human readable status of the foreman e.g. ‘Idle’.
• pid (int) – process identifier (PID).
• used_memory (int) – size of used memory in bytes.
• display_name (str) – human readable of the file entry currently being processed by the foreman.
• number_of_consumed_sources (int) – total number of event sources consumed by the foreman.
• number_of_produced_sources (int) – total number of event sources produced by the foreman.
• number_of_consumed_events (int) – total number of events consumed by the foreman.
• number_of_produced_events (int) – total number of events produced by the foreman.
• number_of_consumed_event_tags (int) – total number of event tags consumed by the foreman.
• number_of_produced_event_tags (int) – total number of event tags produced by the foreman.
• number_of_consumed_errors (int) – total number of errors consumed by the foreman.
• number_of_produced_errors (int) – total number of errors produced by the foreman.
• number_of_consumed_reports (int) – total number of event reports consumed by the process.
• number_of_produced_reports (int) – total number of event reports produced by the process.

UpdateTasksStatus(tasks_status)

Updates the tasks status.

Parameters:tasks_status (TasksStatus) – status information about tasks.

UpdateWorkerStatus(identifier, status, pid, used_memory, display_name, number_of_consumed_sources, number_of_produced_sources, number_of_consumed_events, number_of_produced_events, number_of_consumed_event_tags, number_of_produced_event_tags, number_of_consumed_errors, number_of_produced_errors, number_of_consumed_reports, number_of_produced_reports)

Updates the status of a worker.

Parameters:

• identifier (str) – worker identifier.
• status (str) – human readable status of the worker e.g. ‘Idle’.
• pid (int) – process identifier (PID).
• used_memory (int) – size of used memory in bytes.
• display_name (str) – human readable of the file entry currently being processed by the worker.
• number_of_consumed_sources (int) – total number of event sources consumed by the worker.
• number_of_produced_sources (int) – total number of event sources produced by the worker.
• number_of_consumed_events (int) – total number of events consumed by the worker.
• number_of_produced_events (int) – total number of events produced by the worker.
• number_of_consumed_event_tags (int) – total number of event tags consumed by the worker.
• number_of_produced_event_tags (int) – total number of event tags produced by the worker.
• number_of_consumed_errors (int) – total number of errors consumed by the worker.
• number_of_produced_errors (int) – total number of errors produced by the worker.
• number_of_consumed_reports (int) – total number of event reports consumed by the process.
• number_of_produced_reports (int) – total number of event reports produced by the process.

workers_status

The worker status objects sorted by identifier.

class plaso.engine.processing_status.TasksStatus

Bases: object

The status of the tasks.

number_of_abandoned_tasks

int – number of abandoned tasks.

number_of_queued_tasks

int – number of active tasks.

number_of_tasks_pending_merge

int – number of tasks pending merge.

number_of_tasks_processing

int – number of tasks processing.

total_number_of_tasks

int – total number of tasks.

plaso.engine.profiler module

The profiler classes.

class plaso.engine.profiler.BaseMemoryProfiler(identifier, path=None, profiling_sample_rate=1000)

Bases: object

The memory profiler interface.

classmethod IsSupported()

Determines if the profiler is supported.

Returns:True if the profiler is supported. Return type:bool

Sample()

Takes a sample for profiling.

Start()

Starts the profiler.

Stop()

Stops the profiler.

class plaso.engine.profiler.CPUTimeMeasurements

Bases: object

The CPU time measurements.

number_of_samples

int – number of samples.

total_cpu_time

int – total CPU time measured by the samples.

total_system_time

int – total system time measured by the samples.

SampleStart()

Starts measuring the CPU and system time.

SampleStop()

Stops the current measurement and adds the sample.

class plaso.engine.profiler.CPUTimeProfiler(identifier, path=None)

Bases: object

The CPU time profiler.

StartTiming(profile_name)

Starts timing CPU time.

Parameters:profile_name (str) – name of the profile to sample.

StopTiming(profile_name)

Stops timing CPU time.

Parameters:profile_name (str) – name of the profile to sample.

Write()

Writes the CPU time measurements to a sample file.

class plaso.engine.profiler.GuppyMemoryProfiler(identifier, path=None, profiling_sample_rate=1000)

Bases: plaso.engine.profiler.BaseMemoryProfiler

The guppy-based memory profiler.

classmethod IsSupported()

Determines if the profiler is supported.

Returns:True if the profiler is supported. Return type:bool

Start()

Starts the profiler.

Stop()

Stops the profiler.

class plaso.engine.profiler.ParsersProfiler(identifier, path=None)

Bases: plaso.engine.profiler.CPUTimeProfiler

The parsers profiler.

class plaso.engine.profiler.ProcessingProfiler(identifier, path=None)

Bases: plaso.engine.profiler.CPUTimeProfiler

The processing profiler.

class plaso.engine.profiler.SerializersProfiler(identifier, path=None)

Bases: plaso.engine.profiler.CPUTimeProfiler

The serializers profiler.

plaso.engine.single_process module

plaso.engine.worker module

plaso.engine.zeromq_queue module

ZeroMQ implementations of the Plaso queue interface.

class plaso.engine.zeromq_queue.ZeroMQBufferedQueue(buffer_timeout_seconds=2, buffer_max_size=10000, delay_open=True, linger_seconds=10, maximum_items=1000, name=u'Unnamed', port=None, timeout_seconds=5)

Bases: plaso.engine.zeromq_queue.ZeroMQQueue

Parent class for buffered Plaso queues.

Buffered queues use a regular Python queue to store items that are pushed or popped from the queue without blocking on underlying ZeroMQ operations.

This class should not be instantiated directly, a subclass should be instantiated instead.

Close(abort=False)

Closes the queue.

Parameters:

abort (Optional[bool]) – whether the Close is the result of an abort condition. If True, queue contents may be lost.

Raises:

• QueueAlreadyClosed – If the queue is not started, or has already been closed.
• RuntimeError – if closed or terminate event is missing.

Empty()

Removes all items from the internal buffer.

class plaso.engine.zeromq_queue.ZeroMQBufferedReplyBindQueue(buffer_timeout_seconds=2, buffer_max_size=10000, delay_open=True, linger_seconds=10, maximum_items=1000, name=u'Unnamed', port=None, timeout_seconds=5)

Bases: plaso.engine.zeromq_queue.ZeroMQBufferedReplyQueue

A Plaso queue backed by a ZeroMQ REP socket that binds to a port.

This queue may only be used to pop items, not to push.

SOCKET_CONNECTION_TYPE = 1

class plaso.engine.zeromq_queue.ZeroMQBufferedReplyQueue(buffer_timeout_seconds=2, buffer_max_size=10000, delay_open=True, linger_seconds=10, maximum_items=1000, name=u'Unnamed', port=None, timeout_seconds=5)

Bases: plaso.engine.zeromq_queue.ZeroMQBufferedQueue

Parent class for buffered Plaso queues backed by ZeroMQ REP sockets.

This class should not be instantiated directly, a subclass should be instantiated instead.

Instances of this class or subclasses may only be used to push items, not to pop.

PopItem()

Pops an item of the queue.

Provided for compatibility with the API, but doesn’t actually work.

Raises:WrongQueueType – As Pop is not supported by this queue.

PushItem(item, block=True)

Push an item on to the queue.

If no ZeroMQ socket has been created, one will be created the first time this method is called.

Parameters:

• item (object) – item to push on the queue.
• block (Optional[bool]) – whether the push should be performed in blocking or non-block mode.

Raises:

• QueueAlreadyClosed – If the queue is closed.
• QueueFull – If the internal buffer was full and it was not possible to push the item to the buffer within the timeout.
• RuntimeError – if closed event is missing.

class plaso.engine.zeromq_queue.ZeroMQPullConnectQueue(delay_open=True, linger_seconds=10, maximum_items=1000, name=u'Unnamed', port=None, timeout_seconds=5)

Bases: plaso.engine.zeromq_queue.ZeroMQPullQueue

A Plaso queue backed by a ZeroMQ PULL socket that connects to a port.

This queue may only be used to pop items, not to push.

SOCKET_CONNECTION_TYPE = 2

class plaso.engine.zeromq_queue.ZeroMQPullQueue(delay_open=True, linger_seconds=10, maximum_items=1000, name=u'Unnamed', port=None, timeout_seconds=5)

Bases: plaso.engine.zeromq_queue.ZeroMQQueue

Parent class for Plaso queues backed by ZeroMQ PULL sockets.

This class should not be instantiated directly, a subclass should be instantiated instead.

Instances of this class or subclasses may only be used to pop items, not to push.

PopItem()

Pops an item off the queue.

If no ZeroMQ socket has been created, one will be created the first time this method is called.

Returns:

item from the queue.

Return type:

object

Raises:

• QueueEmpty – If the queue is empty, and no item could be popped within the queue timeout.
• RuntimeError – if closed or terminate event is missing.
• zmq.error.ZMQError – If a ZeroMQ error occurs.

PushItem(item, block=True)

Pushes an item on to the queue.

Provided for compatibility with the API, but doesn’t actually work.

Parameters:

• item (object) – item to push on the queue.
• block (Optional[bool]) – whether the push should be performed in blocking or non-block mode.

Raises:

WrongQueueType – As Push is not supported this queue.

class plaso.engine.zeromq_queue.ZeroMQPushBindQueue(delay_open=True, linger_seconds=10, maximum_items=1000, name=u'Unnamed', port=None, timeout_seconds=5)

Bases: plaso.engine.zeromq_queue.ZeroMQPushQueue

A Plaso queue backed by a ZeroMQ PUSH socket that binds to a port.

This queue may only be used to push items, not to pop.

SOCKET_CONNECTION_TYPE = 1

class plaso.engine.zeromq_queue.ZeroMQPushQueue(delay_open=True, linger_seconds=10, maximum_items=1000, name=u'Unnamed', port=None, timeout_seconds=5)

Bases: plaso.engine.zeromq_queue.ZeroMQQueue

Parent class for Plaso queues backed by ZeroMQ PUSH sockets.

This class should not be instantiated directly, a subclass should be instantiated instead.

Instances of this class or subclasses may only be used to push items, not to pop.

PopItem()

Pops an item of the queue.

Provided for compatibility with the API, but doesn’t actually work.

Raises:WrongQueueType – As Pull is not supported this queue.

PushItem(item, block=True)

Push an item on to the queue.

If no ZeroMQ socket has been created, one will be created the first time this method is called.

Parameters:

• item (object) – item to push on the queue.
• block (Optional[bool]) – whether the push should be performed in blocking or non-block mode.

Raises:

• KeyboardInterrupt – if the process is sent a KeyboardInterrupt while pushing an item.
• QueueFull – if it was not possible to push the item to the queue within the timeout.
• RuntimeError – if terminate event is missing.
• zmq.error.ZMQError – if a ZeroMQ specific error occurs.

class plaso.engine.zeromq_queue.ZeroMQQueue(delay_open=True, linger_seconds=10, maximum_items=1000, name=u'Unnamed', port=None, timeout_seconds=5)

Bases: plaso.engine.plaso_queue.Queue

Interface for a ZeroMQ backed queue.

name

str – name to identify the queue.

port

int – TCP port that the queue is connected or bound to. If the queue is not yet bound or connected to a port, this value will be None.

timeout_seconds

int – number of seconds that calls to PopItem and PushItem may block for, before returning queue.QueueEmpty.

Close(abort=False)

Closes the queue.

Parameters:

abort (Optional[bool]) – whether the Close is the result of an abort condition. If True, queue contents may be lost.

Raises:

• QueueAlreadyClosed – If the queue is not started, or has already been closed.
• RuntimeError – if closed or terminate event is missing.

IsBound()

Checks if the queue is bound to a port.

IsConnected()

Checks if the queue is connected to a port.

IsEmpty()

Checks if the queue is empty.

ZeroMQ queues don’t have a concept of “empty” - there could always be messages on the queue that a producer or consumer is unaware of. Thus, the queue is never empty, so we return False. Note that it is possible that a queue is unable to pop an item from a queue within a timeout, which will cause PopItem to raise a QueueEmpty exception, but this is a different condition.

Returns:False, to indicate the the queue isn’t empty. Return type:bool

Open()

Opens this queue, causing the creation of a ZeroMQ socket.

Raises:QueueAlreadyStarted – If the queue is already started, and a socket already exists.

PopItem()

Pops an item off the queue.

Returns:item from the queue. Return type:object Raises:QueueEmpty – If the queue is empty, and no item could be popped within the queue timeout.

PushItem(item, block=True)

Pushes an item on to the queue.

Parameters:

• item (object) – item to push on the queue.
• block (Optional[bool]) – whether the push should be performed in blocking or non-block mode.

Raises:

QueueAlreadyClosed – If the queue is closed.

SOCKET_CONNECTION_BIND = 1

SOCKET_CONNECTION_CONNECT = 2

SOCKET_CONNECTION_TYPE = None

class plaso.engine.zeromq_queue.ZeroMQRequestConnectQueue(delay_open=True, linger_seconds=10, maximum_items=1000, name=u'Unnamed', port=None, timeout_seconds=5)

Bases: plaso.engine.zeromq_queue.ZeroMQRequestQueue

A Plaso queue backed by a ZeroMQ REQ socket that connects to a port.

This queue may only be used to pop items, not to push.

SOCKET_CONNECTION_TYPE = 2

class plaso.engine.zeromq_queue.ZeroMQRequestQueue(delay_open=True, linger_seconds=10, maximum_items=1000, name=u'Unnamed', port=None, timeout_seconds=5)

Bases: plaso.engine.zeromq_queue.ZeroMQQueue

Parent class for Plaso queues backed by ZeroMQ REQ sockets.

This class should not be instantiated directly, a subclass should be instantiated instead.

Instances of this class or subclasses may only be used to pop items, not to push.

PopItem()

Pops an item off the queue.

If no ZeroMQ socket has been created, one will be created the first time this method is called.

Returns:

item from the queue.

Return type:

object

Raises:

• KeyboardInterrupt – if the process is sent a KeyboardInterrupt while popping an item.
• QueueEmpty – if the queue is empty, and no item could be popped within the queue timeout.
• RuntimeError – if terminate event is missing.
• zmq.error.ZMQError – if an error occurs in ZeroMQ.

PushItem(item, block=True)

Pushes an item on to the queue.

Provided for compatibility with the API, but doesn’t actually work.

Parameters:

• item (object) – item to push on the queue.
• block (Optional[bool]) – whether the push should be performed in blocking or non-block mode.

Raises:

WrongQueueType – As Push is not supported this queue.

Module contents