10.1.2. Module: plugin¶

10.1.2.1. Class: Plugin¶

class tanium_hat.plugin.Plugin(plugin_name, plugin_mod, data_path, **kwargs)[source]¶

Bases: object

Plugin class for THAT.

Parameters:	plugin_name (str) – Name of this plugin plugin_mod (object) – Python module object for this plugin data_path (str) – Path to read/write files to/from

Notes

Helper methods provided for mode: analyze_data:

• tanium_hat.plugin.Plugin.load_json_file() - loads a JSON file from config[data_path] and returns it as a python object
• tanium_hat.plugin.Plugin.load_csv_as_df() - loads a CSV file from config[data_path] and returns it as a pandas dataframe
• tanium_hat.plugin.Plugin.clean_df() - Clean a pandas dataframe of any rows that match values in columns and return the cleaned pandas dataframe
• tanium_hat.plugin.Plugin.get_result() - Get a previously calculated result by name and return the result
• tanium_hat.plugin.Plugin.force_int() - Force value to int
• tanium_hat.plugin.Plugin.force_float() - Force value to float
• tanium_hat.plugin.Plugin.resolve_dict_path() - Resolve path by string from a dictionary and return the result

Must call one of the following methods to start a given workflow for a mode:

• tanium_hat.plugin.Plugin.get_tanium_data() for mode: get_tanium_data
• tanium_hat.plugin.Plugin.get_internet_data() for mode: get_internet_data
• tanium_hat.plugin.Plugin.analyze_data() for mode: analyze_data

PLUGIN_NAME¶

str –

• Name of this plugin, set at init

PLUGIN_MOD¶

object –

• Python module for this plugin, set at init

LOG¶

logging.Logger –

• Logger for this instance

ERRORS¶

list –

• Used to track errors in this plugin, managed by tanium_hat.plugin.Plugin.err_handler()

EXCEPTIONS¶

list –

• Used to track exceptions in this plugin, managed by tanium_hat.plugin.Plugin.err_handler()

PKGS¶

dict –

• Dict object holding a number of packages, passed into plugin functions during tanium_hat.plugin.Plugin.get_internet_data(), set at init

DATA_PATH¶

str –

• Full path to DATA directory, set at init.

GTD_RESULTS¶

dict –

• Used by tanium_hat.plugin.Plugin.get_tanium_data() to store results.

GID_RESULTS¶

dict –

• Used by tanium_hat.plugin.Plugin.get_internet_data() to store results.

ANALYZE_RESULTS¶

dict –

• Used by tanium_hat.plugin.Plugin.analyze_data() to store results

FILE_CACHE¶

dict –

• Used by tanium_hat.plugin.Plugin.load_json_file() and tanium_hat.plugin.Plugin.load_csv_as_df() to cache file loads

__init__(plugin_name, plugin_mod, data_path, **kwargs)[source]¶

Constructor.

_sep1()[source]¶

Log a level 1 separation line.

_sep2()[source]¶

Log a level 2 separation line.

_sep3()[source]¶

Log a level 3 separation line.

_sep4()[source]¶

Log a level 4 separation line.

analyze_data(**kwargs)[source]¶

Plugin mode entry point for analyze_data.

• Uses tanium_hat.plugin.Plugin.get_mode_defs() to get the attribute ANALYZE_DATA from tanium_hat.plugin.Plugin.PLUGIN_MOD
• Iterates over each definition from ANALYZE_DATA and uses tanium_hat.plugin.Plugin.get_analyze_result() to execute the calculation and get the result
• Stores the calculation result under function_name in tanium_hat.plugin.Plugin.GID_RESULTS

Returns:	self.ANALYZE_RESULTS – Tracking dict populated by tanium_hat.plugin.Plugin.get_analyze_result()
Return type:	dict

ask_question(handler, filename, **kwargs)[source]¶

Ask question wrapper around PyTan to track timings, amongst other things.

• Stores tracking information under filename in tanium_hat.plugin.Plugin.GTD_RESULTS

Parameters:	handler (pytan.handler.Handler) – Instantiated PyTan handler providing connection to Tanium Platform filename (str) – filename to save question results to
Returns:	ret – Tracking information for this particular asked question
Return type:	dict

clean_column_value(df, col, val)[source]¶

Clean a pandas dataframe of any rows that match value in a given column.

Helper method for use in analyze_data calculations.

Parameters:	df (pandas.DataFrame) – pandas dataframe to clean col (str) – column to search when looking for matching values val (str) – rows will be removed if column startswith value
Returns:	ret – cleaned pandas dataframe
Return type:	pandas.DataFrame

clean_df(df, **kwargs)[source]¶

Clean a pandas dataframe of any rows that match values in columns.

Helper method for use in analyze_data calculations.

Parameters:	df (pandas.DataFrame) – pandas dataframe to clean columns (list of str, optional) – default : [] list of columns to search when looking for matching values values (list of str, optional) – default : tanium_hat.constants.NOISE_VALUES rows will be removed if any columns contain any of these values add_values (list of str, optional) – default : [] add these str to values remove_values (list of str, optional) – default : [] remove these str from values
Returns:	ret – cleaned pandas dataframe
Return type:	pandas.DataFrame

err_handler(err_str, e=None)[source]¶

Error handler.

• Uses tanium_kit.tools.orig_tb() to get the current exception string, if any
• Appends exception string to tanium_hat.plugin.Plugin.EXCEPTIONS
• Appends error string to tanium_hat.plugin.Plugin.ERRORS
• Logs exception to debug level
• Logs error message to debug level
• Logs PYTHONPATH to debug level

Parameters:	err_str (str) – error string to log/track/spew src (str, optional) – Default : self.__class__.__name__ where this error came from

force_float(v, d=0.0)[source]¶

Force value to float using tanium_hat.plugin.Plugin.force_val_wrap().

Helper method for use in analyze_data calculations.

Parameters:	v (object) – the value to force to float d (float, optional) – default : 0 if v can not be forced to float, default to this value
Returns:	ret – whatever the result of forcing v to float is
Return type:	float

force_int(v, d=0)[source]¶

Force value to int using tanium_hat.plugin.Plugin.force_val_wrap().

Helper method for use in analyze_data calculations.

Parameters:	v (object) – the value to force to int d (int, optional) – default : 0 if v can not be forced to int, default to this value
Returns:	ret – whatever the result of forcing v to int is
Return type:	int

force_val_wrap(v, t, d=0)[source]¶

Force value to type wrapper.

Helper method for use in analyze_data calculations.

Parameters:	v (object) – the value to force to type t t (object) – the python type to force value to d (object, optional) – default : 0 if v can not be forced to type t, default to this value
Returns:	ret – whatever the result of forcing v to t is
Return type:	object

get_analyze_result(name, exec_str)[source]¶

Execute calculation and return result.

Parameters:	name (str) – name of this calculation exec_str (str) – str to exec
Returns:	result – Whatever result exec_str returned
Return type:	object

get_function_result(wequests, mode_def, **kwargs)[source]¶

Execute function from the plugin module and return result.

• Functions are passed the following arguments:
  • wequests : Instantiated Wequests wrapper around requests package
  • pkgs : tanium_hat.plugin.Plugin.PKGS
  • kwargs : the kwargs passed to this method

Parameters:	wequests (tanium_kit.wequests.Wequests) – Instantiated Wequests wrapper around requests package mode_def (str) – function name to get as an attribute from tanium_hat.plugin.Plugin.PLUGIN_MOD
Returns:	result – Whatever function mode_def returned
Return type:	object

get_internet_data(wequests, **kwargs)[source]¶

Plugin mode entry point for get_internet_data.

• Uses tanium_hat.plugin.Plugin.get_mode_defs() to get the attribute GET_INTERNET_DATA from tanium_hat.plugin.Plugin.PLUGIN_MOD
• Iterates over each definition from GET_INTERNET_DATA and uses tanium_hat.plugin.Plugin.get_function_result() to execute the function and get the result
• Stores the function result under function_name in tanium_hat.plugin.Plugin.GID_RESULTS

Parameters:	wequests (tanium_kit.wequests.Wequests) – Instantiated Wequests wrapper around requests package
Returns:	self.GID_RESULTS – Tracking dict populated by tanium_hat.plugin.Plugin.get_function_result()
Return type:	dict

get_mode_defs(mode, attr_type)[source]¶

Get a set of definitions for a given mode from the plugin module.

• Used by mode: all modes!

Parameters:	mode (str) – get this string as an uppercased attribute from tanium_hat.plugin.Plugin.PLUGIN_MOD attr_type (object) – validate that the fetched attribute is of this type
Returns:	ret – the value of uppercased mode from tanium_hat.plugin.Plugin.PLUGIN_MOD
Return type:	object

get_order(default=1000)[source]¶

Get the priority for this plugin.

Parameters:	default (int, optional) – default : 1000 if PRIORITY not set as an attribute in tanium_hat.plugin.Plugin.PLUGIN_MOD, return this as the priority
Returns:	ret – the priority for this plugin
Return type:	int

get_result(target)[source]¶

Get a previously calculated result.

Helper method for use in analyze_data calculations.

Parameters:	target (str) – the key name of the previous result to get the value of
Returns:	ret – whatever the result of target is from tanium_hat.plugin.Plugin.ANALYZE_RESULTS “RESULT FOR {} NOT AVAILABLE” if target not defined
Return type:	object

get_tanium_data(handler, **kwargs)[source]¶

Plugin mode entry point for get_tanium_data.

• Uses tanium_hat.plugin.Plugin.get_mode_defs() to get the attribute GET_TANIUM_DATA from tanium_hat.plugin.Plugin.PLUGIN_MOD
• Iterates over each definition from GET_TANIUM_DATA and uses tanium_hat.plugin.Plugin.ask_question() to ask the question

Parameters:	handler (pytan.handler.Handler) – Instantiated PyTan handler providing connection to Tanium Platform
Returns:	self.GTD_RESULTS – Tracking dict populated by tanium_hat.plugin.Plugin.ask_question()
Return type:	dict

load_csv_as_df(filename, **kwargs)[source]¶

Load a CSV file as a pandas pandas.DataFrame.

Helper method for use in analyze_data calculations.

Parameters:	filename (str) – filename of CSV to load as a dataframe force_refresh (bool, optional) – default : False True : ignore tanium_hat.plugin.Plugin.FILE_CACHE and re-load the file even if it was already loaded False : return data frame from tanium_hat.plugin.Plugin.FILE_CACHE if exists, else load the file data_path (str, optional) – default : tanium_hat.plugin.Plugin.DATA_PATH path to load CSV file from
Returns:	ret – loaded pandas dataframe
Return type:	pandas.DataFrame

load_json_file(filename, **kwargs)[source]¶

Load a JSON file as a dict.

Helper method for use in analyze_data calculations.

Parameters:	filename (str) – filename of JSON to load as a dataframe force_refresh (bool, optional) – default : False True : ignore tanium_hat.plugin.Plugin.FILE_CACHE and re-load the file even if it was already loaded False : return data frame from tanium_hat.plugin.Plugin.FILE_CACHE if exists, else load the file data_path (str, optional) – default : tanium_hat.plugin.Plugin.DATA_PATH path to load JSON file from
Returns:	ret
Return type:	dict

resolve_dict_path(path, source)[source]¶

Resolve dict path from source using tanium_kit.tools.dict_path().

Helper method for use in analyze_data calculations.

Parameters:	path (str) – the path to descend down a nested dictionary, seperated by ‘/’ i.e. “Settings/Platform/Version” would get the result of source[“Settings”][“Platform”][“Version”] source (dict) – the dict to search for path
Returns:	ret – whatever the result of path from source is
Return type:	object