plaso.engine package

Submodules

plaso.engine.artifact_filters module

Helper to create filters based on forensic artifact definitions.

class plaso.engine.artifact_filters.ArtifactDefinitionsFiltersHelper(artifacts_registry, knowledge_base)

Bases: plaso.engine.filters_helper.CollectionFiltersHelper

Helper to create collection filters based on artifact definitions.

Builds collection filters from forensic artifact definitions.

For more information about Forensic Artifacts see: https://github.com/ForensicArtifacts/artifacts/blob/master/docs/Artifacts%20definition%20format%20and%20style%20guide.asciidoc

file_system_artifact_names

names of artifacts definitions that generated file system find specifications.

Type

set[str]

registry_artifact_names

names of artifacts definitions that generated Windows Registry find specifications.

Type

set[str]

BuildFindSpecs(artifact_filter_names, environment_variables=None)

Builds find specifications from artifact definitions.

Parameters

• artifact_filter_names (list[str]) – names of artifact definitions that are used for filtering file system and Windows Registry key paths.

• environment_variables (Optional[list[EnvironmentVariableArtifact]]) – environment variables.

classmethod CheckKeyCompatibility(key_path)

Checks if a Windows Registry key path is supported by dfWinReg.

Parameters

key_path (str) – path of the Windows Registry key.

Returns

True if key is compatible or False if not.

Return type

bool

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

credential data.

Type

bytes

credential_type

credential type.

Type

str

path_spec

path specification.

Type

dfvfs.PathSpec

CONTAINER_TYPE = '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

filter that specifies which events to include.

Type

objectfilter.Filter

text_prepend

text to prepend to every event.

Type

str

CONTAINER_TYPE = '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

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

Type

int

hasher_names_string

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

Type

str

process_archives

True if archive files should be scanned for file entries.

Type

bool

process_compressed_streams

True if file content in compressed streams should be processed.

Type

bool

yara_rules_string

Yara rule definitions.

Type

str

CONTAINER_TYPE = 'extraction_configuration'

class plaso.engine.configurations.InputSourceConfiguration

Bases: plaso.containers.interface.AttributeContainer

Configuration settings of an input source.

mount_path

path of a “mounted” directory input source.

Type

str

CONTAINER_TYPE = 'input_source'

class plaso.engine.configurations.ProcessingConfiguration

Bases: plaso.containers.interface.AttributeContainer

Configuration settings for processing.

artifact_filters

names of artifact definitions that are used for filtering file system and Windows Registry key paths.

Type

Optional list[str]

credentials

credential configurations.

Type

list[CredentialConfiguration]

data_location

path to the data files.

Type

str

debug_output

True if debug output should be enabled.

Type

bool

event_extraction

event extraction configuration.

Type

EventExtractionConfiguration

extraction

extraction configuration.

Type

ExtractionConfiguration

filter_file

path to a file with find specifications.

Type

str

input_source

input source configuration.

Type

InputSourceConfiguration

log_filename

name of the log file.

Type

str

parser_filter_expression

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

Type

str

preferred_year

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

Type

int

profiling

profiling configuration.

Type

ProfilingConfiguration

temporary_directory

path of the directory for temporary files.

Type

str

CONTAINER_TYPE = 'processing_configuration'

class plaso.engine.configurations.ProfilingConfiguration

Bases: plaso.containers.interface.AttributeContainer

Configuration settings for profiling.

directory

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

Type

str

profilers

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.

• ‘storage’, which profiles storage reads and writes.

Type

set(str)

sample_rate

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

Type

int

CONTAINER_TYPE = '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

HaveProfileStorage()

Determines if storage profiling is configured.

Returns

True if storage profiling is configured.

Return type

bool

HaveProfileTaskQueue()

Determines if task queue profiling is configured.

Returns

True if task queue profiling is configured.

Return type

bool

HaveProfileTasks()

Determines if tasks profiling is configured.

Returns

True if task queue 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

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.

ReadFromFile(path)

Reads the path filters from the filter file.

Parameters

path (str) – path to a filter file.

Returns

path filters.

Return type

list[PathFilter]

plaso.engine.filters_helper module

Collection filters helper.

class plaso.engine.filters_helper.CollectionFiltersHelper

Bases: object

Helper for collection filters.

excluded_file_system_find_specs

file system find specifications of paths to exclude from the collection.

Type

list[dfvfs.FindSpec]

included_file_system_find_specs

file system find specifications of paths to include in the collection.

Type

list[dfvfs.FindSpec]

registry_find_specs

Windows Registry find specifications.

Type

list[dfwinreg.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

The 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

codepage of the current session.

Type

str

hostname

hostname of the current session.

Type

str

timezone

timezone of the current session.

Type

datetime.tzinfo

user_accounts

user accounts of the current session.

Type

list[UserAccountArtifact]

year

year of the current session.

Type

int

plaso.engine.logger module

The engine sub module logger.

plaso.engine.path_filters module

Path filters.

Path filters are specified in filter files and are used during collection to include or exclude file system paths.

class plaso.engine.path_filters.PathCollectionFiltersHelper

Bases: plaso.engine.filters_helper.CollectionFiltersHelper

Path collection filters helper.

BuildFindSpecs(path_filters, environment_variables=None)

Builds find specifications from path filters.

Parameters

• path_filters (list[PathFilter]) – path filters.

• environment_variables (Optional[list[EnvironmentVariableArtifact]]) – environment variables.

class plaso.engine.path_filters.PathFilter(filter_type, description=None, path_separator='/', paths=None)

Bases: object

Path filter.

description

description of the purpose of the filter or None if not set.

Type

str

filter_type

indicates if the filter should include or excludes paths during collection.

Type

str

path_separator

path segment separator.

Type

str

paths

paths to filter.

Type

list[str]

FILTER_TYPE_EXCLUDE = 'exclude'

FILTER_TYPE_INCLUDE = 'include'

plaso.engine.path_helper module

The path helper.

class plaso.engine.path_helper.PathHelper

Bases: object

Class that implements the path helper.

classmethod ExpandGlobStars(path, path_separator)

Expands globstars “**” in a path.

A globstar “**” will recursively match all files and zero or more directories and subdirectories.

By default the maximum recursion depth is 10 subdirectories, a numeric values after the globstar, such as “**5”, can be used to define the maximum recursion depth.

Parameters

• path (str) – path to be expanded.

• path_separator (str) – path segment separator.

Returns

String path expanded for each glob.

Return type

list[str]

classmethod ExpandUsersVariablePath(path, path_separator, user_accounts)

Expands a path with a users variable, e.g. %%users.homedir%%.

Parameters

• path (str) – path with users variable.

• path_separator (str) – path segment separator.

• user_accounts (list[UserAccountArtifact]) – user accounts.

Returns

paths for which the users variables have been expanded.

Return type

list[str]

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 ExpandWindowsPathSegments(path_segments, environment_variables)

Expands a Windows path segments containing environment variables.

Parameters

• path_segments (list[str]) – Windows path segments with environment variables.

• environment_variables (list[EnvironmentVariableArtifact]) – environment variables.

Returns

expanded Windows path segments.

Return type

list[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

Information about running process.

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

Bases: object

The status of the events.

number_of_duplicate_events

number of duplicate events, not including the original.

Type

int

number_of_events_from_time_slice

number of events from time slice.

Type

int

number_of_filtered_events

number of events excluded by the event filter.

Type

int

number_of_macb_grouped_events

number of events grouped based on MACB.

Type

int

total_number_of_events

total number of events in the storage file.

Type

int

class plaso.engine.processing_status.ProcessStatus

Bases: object

The status of an individual process.

display_name

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

Type

str

identifier

process identifier.

Type

str

last_running_time

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

Type

int

number_of_consumed_event_tags

total number of event tags consumed by the process.

Type

int

number_of_consumed_event_tags_delta

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

Type

int

number_of_consumed_events

total number of events consumed by the process.

Type

int

number_of_consumed_events_delta

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

Type

int

number_of_consumed_reports

total number of event reports consumed by the process.

Type

int

number_of_consumed_reports_delta

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

Type

int

number_of_consumed_sources

total number of event sources consumed by the process.

Type

int

number_of_consumed_sources_delta

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

Type

int

number_of_consumed_warnings

total number of warnings consumed by the process.

Type

int

number_of_consumed_warnings_delta

number of warnings consumed by the process since the last status update.

Type

int

number_of_produced_event_tags

total number of event tags produced by the process.

Type

int

number_of_produced_event_tags_delta

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

Type

int

number_of_produced_events

total number of events produced by the process.

Type

int

number_of_produced_events_delta

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

Type

int

number_of_produced_reports

total number of event reports produced by the process.

Type

int

number_of_produced_reports_delta

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

Type

int

number_of_produced_sources

total number of event sources produced by the process.

Type

int

number_of_produced_sources_delta

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

Type

int

number_of_produced_warnings

total number of warnings produced by the process.

Type

int

number_of_produced_warnings_delta

number of warnings produced by the process since the last status update.

Type

int

pid

process identifier (PID).

Type

int

status

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

Type

str

used_memory

size of used memory in bytes.

Type

int

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.

UpdateNumberOfWarnings(number_of_consumed_warnings, number_of_produced_warnings)

Updates the number of warnings.

Parameters

• number_of_consumed_warnings (int) – total number of warnings consumed by the process.

• number_of_produced_warnings (int) – total number of warnings produced by the process.

Returns

True if either number of warnings has increased.

Return type

bool

Raises

ValueError – if the consumed or produced number of warnings 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

True if processing was aborted.

Type

bool

error_path_specs

path specifications that caused critical errors during processing.

Type

list[dfvfs.PathSpec]

events_status

status information about events.

Type

EventsStatus

foreman_status

foreman processing status.

Type

ProcessingStatus

start_time

time that the processing was started. Contains the number of micro seconds since January 1, 1970, 00:00:00 UTC.

Type

float

tasks_status

status information about tasks.

Type

TasksStatus

UpdateEventsStatus(events_status)

Updates the events status.

Parameters

events_status (EventsStatus) – status information about events.

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_reports, number_of_produced_reports, number_of_consumed_warnings, number_of_produced_warnings)

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_warnings (int) – total number of warnings consumed by the foreman.

• number_of_produced_warnings (int) – total number of warnings 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_reports, number_of_produced_reports, number_of_consumed_warnings, number_of_produced_warnings)

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

• number_of_consumed_warnings (int) – total number of warnings consumed by the worker.

• number_of_produced_warnings (int) – total number of warnings produced by the worker.

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

number of abandoned tasks.

Type

int

number_of_queued_tasks

number of active tasks.

Type

int

number_of_tasks_pending_merge

number of tasks pending merge.

Type

int

number_of_tasks_processing

number of tasks processing.

Type

int

total_number_of_tasks

total number of tasks.

Type

int

plaso.engine.profilers module

The profiler classes.

class plaso.engine.profilers.CPUTimeMeasurement

Bases: object

The CPU time measurement.

start_sample_time

start sample time or None if not set.

Type

float

total_cpu_time

total CPU time or None if not set.

Type

float

SampleStart()

Starts measuring the CPU time.

SampleStop()

Stops measuring the CPU time.

class plaso.engine.profilers.CPUTimeProfiler(identifier, configuration)

Bases: plaso.engine.profilers.SampleFileProfiler

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.

class plaso.engine.profilers.GuppyMemoryProfiler(identifier, configuration)

Bases: object

The guppy-based memory profiler.

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.profilers.MemoryProfiler(identifier, configuration)

Bases: plaso.engine.profilers.SampleFileProfiler

The memory profiler.

Sample(profile_name, used_memory)

Takes a sample for profiling.

Parameters

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

• used_memory (int) – amount of used memory in bytes.

class plaso.engine.profilers.ProcessingProfiler(identifier, configuration)

Bases: plaso.engine.profilers.CPUTimeProfiler

The processing profiler.

class plaso.engine.profilers.SampleFileProfiler(identifier, configuration)

Bases: object

Shared functionality for sample file-based profilers.

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.profilers.SerializersProfiler(identifier, configuration)

Bases: plaso.engine.profilers.CPUTimeProfiler

The serializers profiler.

class plaso.engine.profilers.StorageProfiler(identifier, configuration)

Bases: plaso.engine.profilers.SampleFileProfiler

The storage profiler.

Sample(operation, description, data_size, compressed_data_size)

Takes a sample of data read or written for profiling.

Parameters

• operation (str) – operation, either ‘read’ or ‘write’.

• description (str) – description of the data read.

• data_size (int) – size of the data read in bytes.

• compressed_data_size (int) – size of the compressed data read in bytes.

class plaso.engine.profilers.TaskQueueProfiler(identifier, configuration)

Bases: plaso.engine.profilers.SampleFileProfiler

The task queue profiler.

Sample(tasks_status)

Takes a sample of the status of queued tasks for profiling.

Parameters

tasks_status (TasksStatus) – status information about tasks.

class plaso.engine.profilers.TasksProfiler(identifier, configuration)

Bases: plaso.engine.profilers.SampleFileProfiler

The tasks profiler.

Sample(task, status)

Takes a sample of the status of a task for profiling.

Parameters

• task (Task) – a task.

• status (str) – status.

plaso.engine.single_process module

plaso.engine.tagging_file module

Tagging file.

class plaso.engine.tagging_file.TaggingFile(path)

Bases: object

Tagging file that defines one or more event tagging rules.

GetEventTaggingRules()

Retrieves the event tagging rules from the tagging file.

Returns

tagging rules, that consists of one or more

filter objects per label.

Return type

dict[str, FilterObject]

Raises

TaggingFileError – if a filter expression cannot be compiled.

plaso.engine.worker module

plaso.engine.yaml_filter_file module

YAML-based filter file.

class plaso.engine.yaml_filter_file.YAMLFilterFile

Bases: object

YAML-based filter file.

A YAML-based filter file contains one or more path filters. description: Include filter with Linux paths. type: include path_separator: ‘/’ paths: - ‘/usr/bin’

Where: * description, is an optional description of the purpose of the path filter; * type, defines the filter type, which can be “include” or “exclude”; * path_separator, defines the path segment separator, which is “/” by default; * paths, defines regular expression of paths to filter on.

Note that the regular expression need to be defined per path segment, for example to filter “/usr/bin/echo” and “/usr/sbin/echo” the following expression could be defined “/usr/(bin|sbin)/echo”.

Note that when the path segment separator is defined as “” it needs to be escaped as “", since “” is used by the regular expression as escape character.

A path may contain path expansion attributes, for example: %{SystemRoot}\System32

ReadFromFile(path)

Reads the path filters from the YAML-based filter file.

Parameters

path (str) – path to a filter file.

Returns

path filters.

Return type

list[PathFilter]

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='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='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='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-blocking 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='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='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

• 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 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-blocking 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='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='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-blocking 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='Unnamed', port=None, timeout_seconds=5)

Bases: plaso.engine.plaso_queue.Queue

Interface for a ZeroMQ backed queue.

name

name to identify the queue.

Type

str

port

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.

Type

int

timeout_seconds

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

Type

int

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-blocking 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='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='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-blocking mode.

Raises

WrongQueueType – As Push is not supported this queue.

Module contents