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:
plaso.analysis.interface.AnalysisPlugin
Analyze browser search entries from events.
-
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
-
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
= 'browser_search'¶
-
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
-
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
-
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.
-
abstract
-
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
= []¶
-
-
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
-
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¶
-
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
-
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'¶
-
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.
-
classmethod
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.
- 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.
-
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.
-
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.
-
-
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.
-
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
-
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'¶
-
plaso.analysis.tagging module¶
Analysis plugin that labels events according to rules in a tagging file.
-
class
plaso.analysis.tagging.
TaggingAnalysisPlugin
[source]¶ Bases:
plaso.analysis.interface.AnalysisPlugin
Analysis plugin that labels events according to rules in a tagging file.
-
ExamineEvent
(mediator, event, event_data, event_data_stream)[source]¶ Labels events according to the rules in a tagging 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'¶
-
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
-
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.
-
-
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.
-
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'¶
-
-
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']¶
-
plaso.analysis.windows_services module¶
A plugin to enable quick triage of Windows Services.
-
class
plaso.analysis.windows_services.
WindowsService
(*args: Any, **kwargs: Any)[source]¶ Bases:
yaml.
Class to represent a Windows Service.
-
image_path
¶ value of the ImagePath value of the service key.
- Type
str
-
name
¶ name of the service
- Type
str
-
object_name
¶ value of the ObjectName value of the service key.
- Type
str
-
service_dll
¶ value of the ServiceDll value in the service’s Parameters subkey.
- Type
str
-
service_type
¶ value of the Type value of the service key.
- Type
int
-
source
¶ tuple containing the path and registry key describing where the service was found
- Type
tuple[str, str]
-
start_type
¶ value of the Start value of the service key.
- Type
int
-
COMPARE_EXCLUDE
= frozenset({'sources'})¶
-
classmethod
FromEventData
(event_data, event_data_stream)[source]¶ Creates a service object from event data.
- Parameters
event_data (EventData) – event data.
event_data_stream (EventDataStream) – event data stream.
- Returns
service.
- Return type
-
HumanReadableStartType
()[source]¶ Return a human readable string describing the start type value.
- Returns
human readable description of the start type value.
- Return type
str
-
HumanReadableType
()[source]¶ Return a human readable string describing the type value.
- Returns
human readable description of the type value.
- Return type
str
-
__eq__
(other_service)[source]¶ Custom equality method so that we match near-duplicates.
Compares two service objects together and evaluates if they are the same or close enough to be considered to represent the same service.
For two service objects to be considered the same they need to have the the same set of attributes and same values for all their attributes, other than those enumerated as reserved in the COMPARE_EXCLUDE constant.
- Parameters
other_service (WindowsService) – service we are testing for equality.
- Returns
whether the services are equal.
- Return type
bool
-
yaml_tag
= '!WindowsService'¶
-
-
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
-
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'¶
-
Module contents¶
This file imports Python modules that register analysis plugins.