plaso.analysis package

Submodules

plaso.analysis.browser_search module

A plugin that extracts browser history from events.

class plaso.analysis.browser_search.BrowserSearchPlugin[source]

Bases: AnalysisPlugin

Analyze browser search entries from events.

CompileReport(analysis_mediator)[source]

Compiles an analysis report.

Parameters: analysis_mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfVFS.
Returns: analysis report.
Return type: AnalysisReport

ExamineEvent(analysis_mediator, event, event_data, event_data_stream)[source]

Analyzes an event.

Parameters

analysis_mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfVFS.
event (EventObject) – event.
event_data (EventData) – event data.
event_data_stream (EventDataStream) – event data stream.

NAME = 'browser_search'

plaso.analysis.chrome_extension module

Analysis plugin to gather information about Chrome extensions.

class plaso.analysis.chrome_extension.ChromeExtensionPlugin[source]

Bases: AnalysisPlugin

Analysis plugin to gather information about Chrome extensions.

CompileReport(analysis_mediator)[source]

Compiles an analysis report.

Parameters: analysis_mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfVFS.
Returns: analysis report.
Return type: AnalysisReport

ExamineEvent(analysis_mediator, event, event_data, event_data_stream)[source]

Analyzes an event.

Parameters

analysis_mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfVFS.
event (EventObject) – event to examine.
event_data (EventData) – event data.
event_data_stream (EventDataStream) – event data stream.

NAME = 'chrome_extension'

plaso.analysis.definitions module

This file contains the definitions for analysis plugins.

plaso.analysis.hash_tagging module

This file contains the interface for analysis plugins.

class plaso.analysis.hash_tagging.HTTPHashAnalyzer(hash_queue, hash_analysis_queue, hashes_per_batch=1, lookup_hash='sha256', wait_after_analysis=0)[source]

Bases: HashAnalyzer

Interface for hash analysis thread that uses HTTP(S)

abstract Analyze(hashes)[source]

Analyzes a list of hashes.

Parameters: hashes (list[str]) – hashes to look up.
Returns: analysis results.
Return type: list[HashAnalysis]

MakeRequestAndDecodeJSON(url, method, **kwargs)[source]

Make a HTTP request and decode the results as JSON.

Parameters

url (str) – URL to make a request to.
method (str) – HTTP method to used to make the request. GET and POST are supported.
kwargs – parameters to the requests .get() or post() methods, depending on the value of the method parameter.

Returns

body of the HTTP response, decoded from JSON.

Return type

dict[str, object]

Raises

ConnectionError – If it is not possible to connect to the given URL, or it the request returns a HTTP error.
ValueError – If an invalid HTTP method is specified.

class plaso.analysis.hash_tagging.HashAnalysis(subject_hash, hash_information)[source]

Bases: object

Analysis information about a hash.

hash_information

object containing information about the hash.

Type: object

subject_hash

hash that was analyzed.

Type: str

class plaso.analysis.hash_tagging.HashAnalyzer(hash_queue, hash_analysis_queue, hashes_per_batch=1, lookup_hash='sha256', wait_after_analysis=0)[source]

Bases: Thread

Interface of a hash analyzer threads.

analyses_performed

number of analysis batches completed by this analyzer.

Type: int

hashes_per_batch

maximum number of hashes to analyze at once.

Type: int

lookup_hash

name of the hash attribute to look up.

Type: str

seconds_spent_analyzing

number of seconds this analyzer has spent performing analysis (as opposed to waiting on queues, etc.)

Type: int

wait_after_analysis

number of seconds the analyzer will sleep for after analyzing a batch of hashes.

Type: int

abstract Analyze(hashes)[source]

Analyzes a list of hashes.

Parameters: hashes (list[str]) – list of hashes to look up.
Returns: list of results of analyzing the hashes.
Return type: list[HashAnalysis]

EMPTY_QUEUE_WAIT_TIME = 4

SUPPORTED_HASHES = []

SetLookupHash(lookup_hash)[source]

Sets the lookup hash to query.

Parameters: lookup_hash (str) – name of the hash attribute to look up.
Raises: ValueError – if the lookup hash is not supported.

SignalAbort()[source]: Instructs the hash analyzer to abort.

run()[source]: The method called by the threading library to start the thread.

class plaso.analysis.hash_tagging.HashTaggingAnalysisPlugin(analyzer_class)[source]

Bases: AnalysisPlugin

An interface for plugins that tag events based on the source file hash.

An implementation of this class should be paired with an implementation of the HashAnalyzer interface.

CompileReport(analysis_mediator)[source]

Compiles an analysis report.

Parameters: analysis_mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfVFS.
Returns: report.
Return type: AnalysisReport

DATA_TYPES = []

DEFAULT_QUEUE_TIMEOUT = 4

EstimateTimeRemaining()[source]

Estimates how long until all hashes have been analyzed.

Returns: estimated number of seconds until all hashes have been analyzed.
Return type: int

ExamineEvent(analysis_mediator, event, event_data, event_data_stream)[source]

Evaluates whether an event contains the right data for a hash lookup.

Parameters

analysis_mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfVFS.
event (EventObject) – event.
event_data (EventData) – event data.
event_data_stream (EventDataStream) – event data stream.

SECONDS_BETWEEN_STATUS_LOG_MESSAGES = 30

SetLookupHash(lookup_hash)[source]

Sets the hash to query.

Parameters: lookup_hash (str) – name of the hash attribute to look up.

plaso.analysis.interface module

This file contains the interface for analysis plugins.

class plaso.analysis.interface.AnalysisPlugin[source]

Bases: object

Class that defines the analysis plugin interface.

CompileReport(analysis_mediator)[source]

Compiles a report of the analysis.

After the plugin has received every copy of an event to analyze this function will be called so that the report can be assembled.

Parameters: analysis_mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfVFS.
Returns: report.
Return type: AnalysisReport

abstract ExamineEvent(analysis_mediator, event, event_data, event_data_stream)[source]

Analyzes an event.

Parameters

analysis_mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfVFS.
event (EventObject) – event.
event_data (EventData) – event data.
event_data_stream (EventDataStream) – event data stream.

NAME = 'analysis_plugin'

TEST_PLUGIN = False

property plugin_name

name of the plugin.

Type: str

plaso.analysis.logger module

The analysis sub module logger.

plaso.analysis.manager module

This file contains the analysis plugin manager class.

class plaso.analysis.manager.AnalysisPluginManager[source]

Bases: object

Analysis plugin manager.

classmethod DeregisterPlugin(plugin_class)[source]

Deregisters an analysis plugin class.

The analysis plugin classes are identified by their lower case name.

Parameters: plugin_class (type) – class of the analysis plugin.
Raises: KeyError – if an analysis plugin class is not set for the corresponding name.

classmethod GetAllPluginInformation()[source]

Retrieves a list of the registered analysis plugins.

Returns

the name, docstring and type string of each: analysis plugin in alphabetical order.

Return type

list[tuple[str, str, str]]

classmethod GetPluginNames()[source]

Retrieves the analysis plugin names.

Returns: analysis plugin names.
Return type: list[str]

classmethod GetPluginObjects(plugin_names)[source]

Retrieves the plugin objects.

Parameters: plugin_names (list[str]) – names of plugins that should be retrieved.
Returns: analysis plugins per name.
Return type: dict[str, AnalysisPlugin]

classmethod GetPlugins()[source]

Retrieves the registered analysis plugin classes.

Yields

tuple –

containing:

str: name of the plugin type: plugin class

classmethod RegisterPlugin(plugin_class)[source]

Registers an analysis plugin class.

Then analysis plugin classes are identified based on their lower case name.

Parameters: plugin_class (type) – class of the analysis plugin.
Raises: KeyError – if an analysis plugin class is already set for the corresponding name.

classmethod RegisterPlugins(plugin_classes)[source]

Registers analysis plugin classes.

The analysis plugin classes are identified based on their lower case name.

Parameters: plugin_classes (list[type]) – classes of the analysis plugin.
Raises: KeyError – if an analysis plugin class is already set for the corresponding name.

plaso.analysis.mediator module

The analysis plugin mediator object.

class plaso.analysis.mediator.AnalysisMediator(session, knowledge_base, data_location=None)[source]

Bases: object

Analysis plugin mediator.

analysis_reports_counter

number of analysis reports per analysis plugin.

Type: collections.Counter

event_labels_counter

number of event tags per label.

Type: collections.Counter

last_activity_timestamp

timestamp received that indicates the last time activity was observed. The last activity timestamp is updated when the mediator produces an attribute container, such as an event tag. This timestamp is used by the multi processing worker process to indicate the last time the worker was known to be active. This information is then used by the foreman to detect workers that are not responding (stalled).

Type: int

number_of_produced_analysis_reports

number of produced analysis reports.

Type: int

number_of_produced_event_tags

number of produced event tags.

Type: int

GetDisplayNameForPathSpec(path_spec)[source]

Retrieves the display name for a path specification.

Parameters: path_spec (dfvfs.PathSpec) – path specification.
Returns: human readable version of the path specification.
Return type: str

GetUsernameForPath(path)[source]

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

ProduceAnalysisReport(plugin)[source]

Produces an analysis report.

Parameters: plugin (AnalysisPlugin) – plugin.

ProduceAnalysisResult(analysis_result)[source]

Produces an analysis result attribute.

Parameters: analysis_result (AttributeContainer) – analysis result.

ProduceAnalysisWarning(message, plugin_name)[source]

Produces an analysis warning.

Parameters

message (str) – message of the warning.
plugin_name (str) – name of the analysis plugin to which the warning applies.

ProduceEventTag(event_tag)[source]

Produces an event tag.

Parameters: event_tag (EventTag) – event tag.

SetStorageWriter(storage_writer)[source]

Sets the storage writer.

Parameters: storage_writer (StorageWriter) – storage writer.

SetTextPrepend(text_prepend)[source]

Sets the text to prepend to the display name.

Parameters: text_prepend (str) – text to prepend to the display name or None if no text should be prepended.

SignalAbort()[source]: Signals the analysis plugins to abort.

property abort

True if the analysis should be aborted.

Type: bool

property data_location

path to the data files.

Type: str

plaso.analysis.nsrlsvr module

Analysis plugin to look up file hashes in nsrlsvr and tag events.

class plaso.analysis.nsrlsvr.NsrlsvrAnalysisPlugin[source]

Bases: HashTaggingAnalysisPlugin

Analysis plugin for looking up hashes in nsrlsvr.

DATA_TYPES = ['fs:stat', 'fs:stat:ntfs']

DEFAULT_LABEL = 'nsrl_present'

NAME = 'nsrlsvr'

SetHost(host)[source]

Sets the address or hostname of the server running nsrlsvr.

Parameters: host (str) – IP address or hostname to query.

SetLabel(label)[source]

Sets the tagging label.

Parameters: label (str) – label to apply to events extracted from files that are present in nsrlsvr.

SetPort(port)[source]

Sets the port where nsrlsvr is listening.

Parameters: port (int) – port to query.

TestConnection()[source]

Tests the connection to nsrlsvr.

Returns: True if nsrlsvr instance is reachable.
Return type: bool

class plaso.analysis.nsrlsvr.NsrlsvrAnalyzer(hash_queue, hash_analysis_queue, **kwargs)[source]

Bases: HashAnalyzer

Analyzes file hashes by consulting an nsrlsvr instance.

analyses_performed

number of analysis batches completed by this analyzer.

Type: int

hashes_per_batch

maximum number of hashes to analyze at once.

Type: int

seconds_spent_analyzing

number of seconds this analyzer has spent performing analysis (as opposed to waiting on queues, etc.)

Type: int

wait_after_analysis

number of seconds the analyzer will sleep for after analyzing a batch of hashes.

Type: int

Analyze(hashes)[source]

Looks up file hashes in nsrlsvr.

Parameters: hashes (list[str]) – hash values to look up.
Returns: analysis results, or an empty list on error.
Return type: list[HashAnalysis]

SUPPORTED_HASHES = ['md5', 'sha1']

SetHost(host)[source]

Sets the address or hostname of the server running nsrlsvr.

Parameters: host (str) – IP address or hostname to query.

SetPort(port)[source]

Sets the port where nsrlsvr is listening.

Parameters: port (int) – port to query.

TestConnection()[source]

Tests the connection to nsrlsvr.

Checks if a connection can be set up and queries the server for the MD5 of an empty file and expects a response. The value of the response is not checked.

Returns: True if nsrlsvr instance is reachable.
Return type: bool

plaso.analysis.sessionize module

Analysis plugin that labels events by session.

class plaso.analysis.sessionize.SessionizeAnalysisPlugin[source]

Bases: AnalysisPlugin

Analysis plugin that labels events by session.

ExamineEvent(analysis_mediator, event, event_data, event_data_stream)[source]

Analyzes an EventObject and tags it as part of a session.

Parameters

analysis_mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfVFS.
event (EventObject) – event to examine.
event_data (EventData) – event data.
event_data_stream (EventDataStream) – event data stream.

NAME = 'sessionize'

SetMaximumPause(maximum_pause_minutes)[source]

Sets the maximum pause interval between events to consider a session.

Parameters: maximum_pause_minutes (int) – maximum pause interval between events that are considered part of the same session, in minutes.

plaso.analysis.tagging module

Analysis plugin that labels events according to rules in a tagging file.

class plaso.analysis.tagging.TaggingAnalysisPlugin[source]

Bases: AnalysisPlugin

Analysis plugin that labels events according to rules in a tagging file.

ExamineEvent(analysis_mediator, event, event_data, event_data_stream)[source]

Labels events according to the rules in a tagging file.

Parameters

analysis_mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfVFS.
event (EventObject) – event to examine.
event_data (EventData) – event data.
event_data_stream (EventDataStream) – event data stream.

NAME = 'tagging'

SetAndLoadTagFile(tagging_file_path)[source]

Sets the tagging file to be used by the plugin.

Parameters: tagging_file_path (str) – path of the tagging file.

plaso.analysis.test_memory module

Analysis plugin for testing exceeding memory consumption.

class plaso.analysis.test_memory.TestMemoryAnalysisPlugin[source]

Bases: AnalysisPlugin

Analysis plugin for testing memory consumption.

CompileReport(analysis_mediator)[source]

Compiles an analysis report.

Parameters: analysis_mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfVFS.
Returns: analysis report.
Return type: AnalysisReport

ExamineEvent(analysis_mediator, event, event_data, event_data_stream)[source]

Analyzes an event.

Parameters

analysis_mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfVFS.
event (EventObject) – event.
event_data (EventData) – event data.
event_data_stream (EventDataStream) – event data stream.

NAME = 'test_memory'

TEST_PLUGIN = True

plaso.analysis.unique_domains_visited module

A plugin to generate a list of domains visited.

class plaso.analysis.unique_domains_visited.UniqueDomainsVisitedPlugin[source]

Bases: AnalysisPlugin

A plugin to generate a list all domains visited.

This plugin will extract domains from browser history events extracted by Plaso. The list produced can be used to quickly determine if there has been a visit to a site of interest, for example, a known phishing site.

ExamineEvent(analysis_mediator, event, event_data, event_data_stream)[source]

Analyzes an event and extracts domains from it.

We only evaluate straightforward web history events, not visits which can be inferred by TypedURLs, cookies or other means.

Parameters

analysis_mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfVFS.
event (EventObject) – event to examine.
event_data (EventData) – event data.
event_data_stream (EventDataStream) – event data stream.

NAME = 'unique_domains_visited'

plaso.analysis.viper module

Analysis plugin to look up files in Viper and tag events.

class plaso.analysis.viper.ViperAnalysisPlugin[source]

Bases: HashTaggingAnalysisPlugin

An analysis plugin for looking up SHA256 hashes in Viper.

DATA_TYPES = ['pe', 'pe:compilation:compilation_time']

NAME = 'viper'

SetHost(host)[source]

Sets the address or hostname of the server running Viper server.

Parameters: host (str) – IP address or hostname to query.

SetPort(port)[source]

Sets the port where Viper server is listening.

Parameters: port (int) – port to query.

SetProtocol(protocol)[source]

Sets the protocol that will be used to query Viper.

Parameters: protocol (str) – protocol to use to query Viper. Either ‘http’ or ‘https’.
Raises: ValueError – if the protocol is not supported.

TestConnection()[source]

Tests the connection to the Viper server.

Returns: True if the Viper server instance is reachable.
Return type: bool

class plaso.analysis.viper.ViperAnalyzer(hash_queue, hash_analysis_queue, **kwargs)[source]

Bases: HTTPHashAnalyzer

Class that analyzes file hashes by consulting Viper.

REST API reference: https://viper-framework.readthedocs.io/en/latest/usage/web.html#api

Analyze(hashes)[source]

Looks up hashes in Viper using the Viper HTTP API.

Parameters: hashes (list[str]) – hashes to look up.
Returns: hash analysis.
Return type: list[HashAnalysis]
Raises: RuntimeError – If no host has been set for Viper.

SUPPORTED_HASHES = ['md5', 'sha256']

SUPPORTED_PROTOCOLS = ['http', 'https']

SetHost(host)[source]

Sets the address or hostname of the server running Viper server.

Parameters: host (str) – IP address or hostname to query.

SetPort(port)[source]

Sets the port where Viper server is listening.

Parameters: port (int) – port to query.

SetProtocol(protocol)[source]

Sets the protocol that will be used to query Viper.

Parameters: protocol (str) – protocol to use to query Viper. Either ‘http’ or ‘https’.
Raises: ValueError – if the protocol is not supported.

TestConnection()[source]

Tests the connection to the Viper server.

Returns: True if the Viper server instance is reachable.
Return type: bool

plaso.analysis.virustotal module

Analysis plugin to look up files in VirusTotal and tag events.

class plaso.analysis.virustotal.VirusTotalAnalysisPlugin[source]

Bases: HashTaggingAnalysisPlugin

An analysis plugin for looking up hashes in VirusTotal.

DATA_TYPES = ['pe', 'pe:compilation:compilation_time']

EnableFreeAPIKeyRateLimit()[source]

Configures Rate limiting for queries to VirusTotal.

The default rate limit for free VirusTotal API keys is 4 requests per minute.

NAME = 'virustotal'

SetAPIKey(api_key)[source]

Sets the VirusTotal API key to use in queries.

Parameters: api_key (str) – VirusTotal API key

TestConnection()[source]

Tests the connection to VirusTotal

Returns: True if VirusTotal is reachable.
Return type: bool

class plaso.analysis.virustotal.VirusTotalAnalyzer(hash_queue, hash_analysis_queue, **kwargs)[source]

Bases: HTTPHashAnalyzer

Class that analyzes file hashes by consulting VirusTotal.

The API is documented here: https://developers.virustotal.com/reference/overview

Analyze(hashes)[source]

Looks up hashes in VirusTotal using the VirusTotal HTTP API.

Parameters: hashes (list[str]) – hashes to look up.
Returns: analysis results.
Return type: list[HashAnalysis]
Raises: RuntimeError – If the VirusTotal API key has not been set.

SUPPORTED_HASHES = ['md5', 'sha1', 'sha256']

SetAPIKey(api_key)[source]

Sets the VirusTotal API key to use in queries.

Parameters: api_key (str) – VirusTotal API key

TestConnection()[source]

Tests the connection to VirusTotal

Returns: True if VirusTotal is reachable.
Return type: bool

Module contents

This file imports Python modules that register analysis plugins.