plaso.analysis package¶

Submodules¶

plaso.analysis.browser_search module¶

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)[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.

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)[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.

NAME = 'file_hashes'¶

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

ExamineEvent(mediator, event)[source]¶

Analyzes an event object.

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

NAME = 'analysis_plugin'¶

URLS = []¶

plugin_name¶: str – name of the plugin.

class plaso.analysis.interface.HTTPHashAnalyzer(hash_queue, hash_analysis_queue, **kwargs)[source]¶

Bases: plaso.analysis.interface.HashAnalyzer

Interface for hash analysis plugins that use HTTP(S)

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.interface.HashAnalysis(subject_hash, hash_information)[source]¶

Bases: object

Analysis information about a hash.

hash_information¶: object – object containing information about the hash.

subject_hash¶: str – hash that was analyzed.

class plaso.analysis.interface.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¶: int – number of analysis batches completed by this analyzer.

hashes_per_batch¶: int – maximum number of hashes to analyze at once.

lookup_hash¶: str – name of the hash attribute to look up.

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

wait_after_analysis¶: int – number of seconds the analyzer will sleep for after analyzing a batch of hashes.

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.interface.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.queue – queue that contains the results of analysis of file hashes.

hash_queue¶: Queue.queue – queue that contains file 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

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)[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.

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

plaso.analysis.nsrlsvr module¶

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

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

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

Analyzes file hashes by consulting an nsrlsvr instance.

analyses_performed¶: int – number of analysis batches completed by this analyzer.

hashes_per_batch¶: int – maximum number of hashes to analyze at once.

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

wait_after_analysis¶: int – number of seconds the analyzer will sleep for after analyzing a batch of hashes.

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)[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.

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)[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.

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)[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.

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.interface.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.interface.HTTPHashAnalyzer

Class that analyzes file hashes by consulting Viper.

REST API reference:: https://viper-framework.readthedocs.org/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.interface.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.interface.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://www.virustotal.com/en/documentation/public-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

plaso.analysis package¶

Submodules¶

plaso.analysis.browser_search module¶

plaso.analysis.chrome_extension module¶

plaso.analysis.definitions module¶

plaso.analysis.file_hashes module¶

plaso.analysis.interface module¶

plaso.analysis.logger module¶

plaso.analysis.manager module¶

plaso.analysis.mediator module¶

plaso.analysis.nsrlsvr module¶

plaso.analysis.sessionize module¶

plaso.analysis.tagging module¶

plaso.analysis.unique_domains_visited module¶

plaso.analysis.viper module¶

plaso.analysis.virustotal module¶

plaso.analysis.windows_services module¶

Module contents¶