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.windows_services module

Module contents