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
-
ENABLE_IN_EXTRACTION
= True¶
-
ExamineEvent
(mediator, event, event_data)[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.
-
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
-
ENABLE_IN_EXTRACTION
= True¶
-
ExamineEvent
(mediator, event, event_data)[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.
-
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
-
ENABLE_IN_EXTRACTION
= False¶
-
ExamineEvent
(mediator, event, event_data)[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.
-
NAME
= 'analysis_plugin'¶
-
URLS
= []¶
-
plugin_name
¶ name of the plugin.
- Type
str
-
-
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 containing information about the hash.
- Type
object
-
subject_hash
¶ hash that was analyzed.
- Type
str
-
-
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
¶ 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
-
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
= []¶
-
-
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 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
-
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)[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.
-
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¶
-
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.
-
classmethod
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
¶ 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.
-
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
-
ENABLE_IN_EXTRACTION
= False¶
-
ExamineEvent
(mediator, event, event_data)[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.
-
NAME
= 'sessionize'¶
-
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
-
ENABLE_IN_EXTRACTION
= True¶
-
ExamineEvent
(mediator, event, event_data)[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.
-
NAME
= 'tagging'¶
-
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
-
ENABLE_IN_EXTRACTION
= True¶
-
ExamineEvent
(mediator, event, event_data)[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.
-
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.
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:
- 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']¶
-