plaso.analysis package

Submodules

plaso.analysis.chrome_extension module

A plugin that gather extension IDs from Chrome history browser.

class plaso.analysis.chrome_extension.ChromeExtensionPlugin[source]

Bases: plaso.analysis.interface.AnalysisPlugin

Convert Chrome extension IDs into names, requires Internet connection.

CompileReport(mediator)[source]

Compiles an analysis report.

Parameters

mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfvfs.

Returns

analysis report.

Return type

AnalysisReport

ENABLE_IN_EXTRACTION = True
ExamineEvent(mediator, event, event_data, event_data_stream)[source]

Analyzes an event.

Parameters

  • 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.file_hashes module

A plugin to generate a list of unique hashes and paths.

class plaso.analysis.file_hashes.FileHashesPlugin[source]

Bases: plaso.analysis.interface.AnalysisPlugin

A plugin for generating a list of file paths and corresponding hashes.

CompileReport(mediator)[source]

Compiles an analysis report.

Parameters

mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfvfs.

Returns

report.

Return type

AnalysisReport

ENABLE_IN_EXTRACTION = True
ExamineEvent(mediator, event, event_data, event_data_stream)[source]

Analyzes an event and creates extracts hashes as required.

Parameters

  • 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 = 'file_hashes'

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: plaso.analysis.hash_tagging.HashAnalyzer

Interface for hash analysis plugins that use 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: threading.Thread

Class that defines the interfaces for hash analyzer threads.

This interface should be implemented once for each hash analysis plugin.

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 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 this analyzer to stop running.

run()[source]

The method called by the threading library to start the thread.

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

Bases: plaso.analysis.interface.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.

hash_analysis_queue

queue that contains the results of analysis of file hashes.

Type

queue.Queue

hash_queue

queue that contains file hashes.

Type

queue.Queue

CompileReport(mediator)[source]

Compiles an analysis report.

Parameters

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(mediator, event, event_data, event_data_stream)[source]

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

Parameters

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

abstract GenerateLabels(hash_information)[source]

Generates a list of strings to tag events with.

Parameters

hash_information (object) – object that mediates the result of the analysis of a hash, as returned by the Analyze() method of the analyzer class associated with this plugin.

Returns

list of labels to apply to events.

Return type

list[str]

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.

abstract CompileReport(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

mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfvfs.

Returns

report.

Return type

AnalysisReport

ENABLE_IN_EXTRACTION = False
abstract ExamineEvent(mediator, event, event_data, event_data_stream)[source]

Analyzes an event.

Parameters

  • 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'
URLS = []
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(show_all=True)[source]

Retrieves a list of the registered analysis plugins.

Parameters

show_all (Optional[bool]) – True if all analysis plugin names should be listed.

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(storage_writer, knowledge_base, data_location=None)[source]

Bases: object

Analysis plugin mediator.

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.

ProduceEventTag(event_tag)[source]

Produces an event tag.

Parameters

event_tag (EventTag) – event tag.

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

property operating_system

operating system or None if not set.

Type

str

plaso.analysis.nsrlsvr module

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

class plaso.analysis.nsrlsvr.NsrlsvrAnalysisPlugin[source]

Bases: plaso.analysis.hash_tagging.HashTaggingAnalysisPlugin

Analysis plugin for looking up hashes in nsrlsvr.

DATA_TYPES = ['fs:stat', 'fs:stat:ntfs']
GenerateLabels(hash_information)[source]

Generates a list of strings that will be used in the event tag.

Parameters

hash_information (bool) – whether the analyzer received a response from nsrlsvr indicating that the hash was present in its loaded NSRL set.

Returns

strings describing the results from nsrlsvr.

Return type

list[str]

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

URLS = ['https://rjhansen.github.io/nsrlsvr/']
class plaso.analysis.nsrlsvr.NsrlsvrAnalyzer(hash_queue, hash_analysis_queue, **kwargs)[source]

Bases: plaso.analysis.hash_tagging.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 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

A plugin to tag events according to rules in a tag file.

class plaso.analysis.sessionize.SessionizeAnalysisPlugin[source]

Bases: plaso.analysis.interface.AnalysisPlugin

Analysis plugin that labels events by session.

CompileReport(mediator)[source]

Compiles an analysis report.

Parameters

mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfvfs.

Returns

analysis report.

Return type

AnalysisReport

ENABLE_IN_EXTRACTION = False
ExamineEvent(mediator, event, event_data, event_data_stream)[source]

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

Parameters

  • 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 gap between events that are part of the same session, in minutes.

plaso.analysis.tagging module

A plugin to tag events according to rules in a tagging file.

class plaso.analysis.tagging.TaggingAnalysisPlugin[source]

Bases: plaso.analysis.interface.AnalysisPlugin

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

CompileReport(mediator)[source]

Compiles an analysis report.

Parameters

mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfvfs.

Returns

analysis report.

Return type

AnalysisReport

ENABLE_IN_EXTRACTION = True
ExamineEvent(mediator, event, event_data, event_data_stream)[source]

Analyzes an EventObject and tags it according to rules in the tag file.

Parameters

  • 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 tag file to be used by the plugin.

Parameters

tagging_file_path (str) – path of the tagging file.

plaso.analysis.unique_domains_visited module

A plugin to generate a list of domains visited.

class plaso.analysis.unique_domains_visited.UniqueDomainsVisitedPlugin[source]

Bases: plaso.analysis.interface.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.

CompileReport(mediator)[source]

Compiles an analysis report.

Parameters

mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfvfs.

Returns

the analysis report.

Return type

AnalysisReport

ENABLE_IN_EXTRACTION = True
ExamineEvent(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

  • 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: plaso.analysis.hash_tagging.HashTaggingAnalysisPlugin

An analysis plugin for looking up SHA256 hashes in Viper.

DATA_TYPES = ['pe:compilation:compilation_time']
GenerateLabels(hash_information)[source]

Generates a list of strings that will be used in the event tag.

Parameters

hash_information (dict[str, object]) – JSON decoded contents of the result of a Viper lookup, as produced by the ViperAnalyzer.

Returns

list of labels to apply to events.

Return type

list[str]

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 an invalid protocol is selected.

TestConnection()[source]

Tests the connection to the Viper server.

Returns

True if the Viper server instance is reachable.

Return type

bool

URLS = ['https://viper.li']
class plaso.analysis.viper.ViperAnalyzer(hash_queue, hash_analysis_queue, **kwargs)[source]

Bases: plaso.analysis.hash_tagging.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: plaso.analysis.hash_tagging.HashTaggingAnalysisPlugin

An analysis plugin for looking up hashes in VirusTotal.

DATA_TYPES = ['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.

GenerateLabels(hash_information)[source]

Generates a list of strings that will be used in the event tag.

Parameters

hash_information (dict[str, object]) – the JSON decoded contents of the result of a VirusTotal lookup, as produced by the VirusTotalAnalyzer.

Returns

strings describing the results from VirusTotal.

Return type

list[str]

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

URLS = ['https://virustotal.com']
class plaso.analysis.virustotal.VirusTotalAnalyzer(hash_queue, hash_analysis_queue, **kwargs)[source]

Bases: plaso.analysis.hash_tagging.HTTPHashAnalyzer

Class that analyzes file hashes by consulting VirusTotal.

Analyze(hashes)[source]

Looks up hashes in VirusTotal using the VirusTotal HTTP API.

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

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

plaso.analysis.windows_services module

A plugin to enable quick triage of Windows Services.

class plaso.analysis.windows_services.WindowsServiceCollection[source]

Bases: object

Class to hold and de-duplicate Windows Services.

AddService(new_service)[source]

Add a new service to the list of ones we know about.

Parameters

new_service (WindowsService) – the service to add.

property services

services in this collection.

Type

list[WindowsService]

class plaso.analysis.windows_services.WindowsServicesAnalysisPlugin[source]

Bases: plaso.analysis.interface.AnalysisPlugin

Provides a single list of for Windows services found in the Registry.

CompileReport(mediator)[source]

Compiles an analysis report.

Parameters

mediator (AnalysisMediator) – mediates interactions between analysis plugins and other components, such as storage and dfvfs.

Returns

report.

Return type

AnalysisReport

ENABLE_IN_EXTRACTION = True
ExamineEvent(mediator, event, event_data, event_data_stream)[source]

Analyzes an event and creates Windows Services as required.

At present, this method only handles events extracted from the Registry.

Parameters

  • 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 = 'windows_services'
SetOutputFormat(output_format)[source]

Sets the output format of the generated report.

Parameters

output_format (str) – format the plugin should used to produce its output.

Module contents

This file imports Python modules that register analysis plugins.