10.1.1. Module: main¶

Bases: object

Main workflow class for THAT.

Must call tanium_hat.main.Main.start() in order to start the workflow.

>>> # initialize the Main class
>>> main = that.main.Main()

>>> # use the default configuration file
>>> main.start()

>>> # or, use a specific configuration file
>>> main.start(config_file="my_config.ini")

CONFIG_FILE¶

str –

• Path to configuration file for this instance

CONFIG¶

dict –

• Unparsed configuration file in dict form, set by tanium_hat.main.Main.load_config_file()

PCONFIG¶

dict –

• Parsed configuration file in dict form, set by tanium_hat.main.Main.parse_config_contents()

LOG¶

logging.Logger –

• Logger for this instance

LH_CON¶

logging.StreamHandler –

• Console log handler for this instance

LH_FILE¶

logging.handlers.RotatingFileHandler –

• File log handler for this instance, set by tanium_hat.main.Main.add_file_logging()

ERRORS¶

dict –

• Used to track errors and where they occurred, managed by tanium_hat.main.Main.err_handler()

EXCEPTIONS¶

dict –

• Used to track exceptions and where they occurred, managed by tanium_hat.main.Main.err_handler()

WEQUESTS¶

tanium_kit.wequests.Wequests –

• Wequests object (wrapper for requests)

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

add_file_logging()[source]¶

Add a file log handler to the root logger that gets DEBUG and above log messages.

• Updates tanium_hat.main.Main.LH_FILE with the file log handler

check_internet()[source]¶

Check to see if an internet connection is available.

Uses tanium_hat.constants.INTERNET_TEST_URL as the url to use for checking internet connectivity.

Returns:	ret – True: Internet available False: Internet not available
Return type:	bool

check_pytan_admin(role_name=u'Administrator')[source]¶

Check if the current pytan user has the Administrator role in Tanium.

• Uses tanium_hat.main.Main.get_user_obj() to get the user object

collect_analyze_results()[source]¶

Collect analayze_data results from plugins.

• Stores tanium_hat.main.Main.PCONFIG under the key “config”.
• Stores tanium_hat.plugin.Plugin.ANALYZE_RESULTS under the key “plugin_name” for each enabled plugin.

Returns:	ret – nested dict with the collected results
Return type:	dict

collect_internet_results()[source]¶

Collect get_internet_data results from plugins.

• Stores tanium_hat.plugin.Plugin.GID_RESULTS into ret.
• Conflicting key names from different plugins will overwrite each other!

Returns:	ret – dict with the collected results
Return type:	dict

collect_tanium_results()[source]¶

Collect get_tanium_data results from plugins.

• Stores tanium_hat.plugin.Plugin.GTD_RESULTS into ret.

Returns:	ret – list of dict with the collected results
Return type:	list

config_check_abs(value, section, entry, **kwargs)[source]¶

Pre-pend value if it is not absolute.

Parameters:	value (str) – value from config file/user section (str) – section in configuration file value came from entry (str) – entry in section in configuration file value came from force_abs (bool, optional) – default : False str : value should be prefixed with str if value is not absolute False : leave value alone
Returns:	ret – value
Return type:	str

config_check_bool(value, section, entry, **kwargs)[source]¶

Convert value into boolean.

Parameters:	value (str) – value from config file/user section (str) – section in configuration file value came from entry (str) – entry in section in configuration file value came from is_bool (bool, optional) – default : False True : value should be converted to bool using tanium_kit.ask.coerce_bool(), ask user if it fails to be converted False : leave value alone
Returns:	ret – value
Return type:	str

config_check_crypt(value, section, entry, **kwargs)[source]¶

Check if value is cryptable.

Parameters:	value (str) – value from config file/user section (str) – section in configuration file value came from entry (str) – entry in section in configuration file value came from is_crypt (bool, optional) – default : False True : value is could be a crypted value, use tanium_kit.tools.deobfuscate() to convert it False : leave value alone
Returns:	ret – value
Return type:	str

config_check_empty(value, section, entry, **kwargs)[source]¶

Check if value is empty.

Parameters:	value (str) – value from config file/user section (str) – section in configuration file value came from entry (str) – entry in section in configuration file value came from empty_ok (bool, optional) – default : False True : value is allowed to be empty False : value is not allowed to be empty, re-ask user if it is empty
Returns:	ret – value
Return type:	str

config_check_int(value, section, entry, **kwargs)[source]¶

Convert value into integer.

Parameters:	value (str) – value from config file/user section (str) – section in configuration file value came from entry (str) – entry in section in configuration file value came from is_int (bool, optional) – default : False True : value should be converted to int using tanium_kit.tools.int_check(), ask user if it fails to be converted False : leave value alone
Returns:	ret – value
Return type:	str

config_check_tmpl(value, section, entry, **kwargs)[source]¶

Templatize value.

Parameters:	value (str) – value from config file/user section (str) – section in configuration file value came from entry (str) – entry in section in configuration file value came from is_template (bool, optional) – default : False True : value should be templatized using tanium_hat.main.Main.config_tmpl() False : leave value alone
Returns:	ret – value
Return type:	str

config_check_value(section, entry, **kwargs)[source]¶

Check if value is defined in config file.

• Checks os.environ for THAT_ENTRY and uses that as value if defined
• Checks if tanium_hat.main.Main.CONFIG is defined/is a dict, asks user for value if not
• Checks tanium_hat.main.Main.CONFIG for entry and uses that as value if found

Parameters:	section (str) – section in configuration file value came from entry (str) – entry in section in configuration file value came from
Returns:	ret – value
Return type:	str

config_tmpl(value, src, quiet=False)[source]¶

Templatize a value.

Parameters:	value (str) – string to templatize using tanium_hat.main.Main.PCONFIG src (str) – where this string came from quiet (bool, optional) – default : False True : Log at debug level False : Log at info level
Returns:	ret – Templatized string
Return type:	str

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

Error handler.

• Uses tanium_kit.tools.orig_tb() to get the current exception string, if any
• Appends exception string to “main” in tanium_hat.main.Main.EXCEPTIONS
• Appends error string to “main” in tanium_hat.main.Main.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

flight_check()[source]¶

Verify that at least one mode and one plugin was selected.

get_config_entry(section, entry, **kwargs)[source]¶

Get the value of an entry from self.CONFIG.

If value not supplied or is not the right type, prompt user for value.

Parameters:	section (str) – section in self.CONFIG to look for entry entry (str) – key in section to get value from self.CONFIG[section][entry] prompt (str) – Prompt to use when asking for value is_bool (bool, optional) – default: False True: value of entry must be a boolean False: value of entry does not have to be a boolean is_int (bool, optional) – default: False True: value of entry must be an integer False: value of entry does not have to be an integer empty_ok (bool, optional) – default: False True: value of entry can be empty False: value of entry can not be empty force_abs (bool, optional) – default: False True: if value of entry is not an absolute path, prepend it with the path of THAT False: leave value of entry alone is_crypt (bool, optional) – default: False True: run value of entry through tanium_kit.tools.deobfuscate() False: leave value of entry alone
Returns:	value – value of entry from config file or from user supplied input
Return type:	str/bool/int

get_enabled_plugins()[source]¶

Determine which plugins to enable.

• Iterates over plugin_modules in tanium_hat.main.Main.PCONFIG to check config/ask user if the plugin is enabled

get_handler()[source]¶

Get a PyTan Handler.

Returns:	ret – PyTan Handler created using credentials from self.PCONFIG
Return type:	pytan.handler.Handler

get_info_json()[source]¶

Get info.json from the Tanium platform server using PyTan.

get_local_plugins()[source]¶

Find the plugins that are available locally.

• Uses tanium_hat.constants.PLUGINS_FOUND to find matching plugins
• Uses tanium_hat.main.Main.load_module() to load each plugin that is found
• Uses tanium_hat.main.Main.load_module() to reload newer plugins
• Updates plugin_modules in tanium_hat.main.Main.PCONFIG with plugin name -> plugin module mapping

get_module_json(name, url)[source]¶

Get json for a module from the Tanium platform server using PyTan.

get_plugin_option(option_name, pname, pmod)[source]¶

Get a plugin option and templatize it for a given plugin.

• Gets the plugin option from tanium_hat.options.PLUGINS
• Uses tanium_hat.main.Main.get_plugin_tmpl() to build a dict for use in templating

Parameters:	option_name (str) – Name of option to get from tanium_hat.options.PLUGINS name (str) – name of plugin pmod (tanium_hat.plugin.Plugin) – module of plugin
Returns:	ret – templatized dict for this plugin option
Return type:	dict

get_plugin_tmpl(pname, pmod)[source]¶

Build a dict to use in templating plugin options.

Parameters:	name (str) – name of plugin pmod (tanium_hat.plugin.Plugin) – module of plugin
Returns:	ret – dict ready for use in templating
Return type:	dict

get_user_obj()[source]¶

Get the user object for the current user.

• Uses tanium_kit.pytanx.get_user_obj() to get the user object

Returns:	user_obj – User object for the currently logged in user ID in handler
Return type:	taniumpy.object_types.user.User

jump_ship(lvl=99)[source]¶

Method called to exit due to error.

Parameters:	lvl (int, optional) – Default: 99 Exit code to end process with

keep_going(m)[source]¶

Ask the user if they wish to keep going using prompt m.

Exit if they say no.

Parameters:	m (str) – prompt to use when asking the user

land()[source]¶

Print out any errors that occurred and exit.

load_config_file(path)[source]¶

Use IniReader() to turn ini file at path into a dictionary.

Parameters:	path (str) – path to ini file to parse
Returns:	ret – ini file contents churned into dict
Return type:	dict

load_enabled_plugins()[source]¶

Load enabled plugins.

• Iterates over plugin_modules in tanium_hat.main.Main.PCONFIG for enabled plugins
• Initializes a tanium_hat.plugin.Plugin object for each enabled plugin
• Updates plugins in tanium_hat.main.Main.PCONFIG with plugin name -> plugin object mapping

load_layout_def()[source]¶

Load the python layout definition file.

• Gets layout_File from tanium_hat.main.Main.PCONFIG
• Uses tanium_hat.main.Main.load_module() to load the module
• Uses tanium_hat.main.Main.load_module() to reload any new layout file
• Uses tanium_hat.pptx_builder.val_layouts() to validate the layouts in the layout definition file

load_layout_pptx()[source]¶

Load the PPTX file referenced by the layout definition file.

• Gets layout_mod.PPTX_INPUT_FILE from tanium_hat.main.Main.PCONFIG

load_module(path, mod_type, mod_attrs=[])[source]¶

Load a python file into a module.

• Uses imp.load_source() to read the file at runtime and load it in as a python module.
• Sets MODULE_PATH and MODULE_FILE as attributes on the returned module.

Parameters:	path (str) – Path to the python file to load as a module mod_type (str) – Type of module mod_attrs (list of str, optional) – Default : tanium_hat.constants.ALWAYS_ATTRS List of attributes that must be defined in the loaded module Attributes supplied here will be appended to tanium_hat.constants.ALWAYS_ATTRS
Returns:	ret – Loaded python module from path
Return type:	object

makedir(path)[source]¶

Make a directory and all leading directories as needed.

Parameters:	path (str) – Directory to make

mode_analyze_data()[source]¶

Run analyze_data for plugins, collect results, create PPTX file.

• Uses tanium_hat.main.Main.run_plugins() to call tanium_hat.plugin.Plugin.analyze_data() on every plugin
• Uses tanium_hat.main.Main.collect_analyze_results() to get the results of analyze_data for all plugins
• Uses tanium_hat.pptx_builder.PptxBuilder to create the PPTX file.

mode_get_internet_data()[source]¶

Run get_internet_data for plugins and write results.

• Uses tanium_hat.main.Main.run_plugins() to call tanium_hat.plugin.Plugin.get_internet_data() on every plugin
• Uses tanium_hat.main.Main.collect_internet_results() to get the results of get_internet_data for all plugins
• Uses tanium_hat.main.Main.write_csv() to write results to tanium_hat.constants.INTERNET_FILE_NAME in data_path

mode_get_tanium_data()[source]¶

Run get_tanium_data for plugins and write results.

• Uses tanium_hat.main.Main.get_handler() to get a PyTan handler connection to Tanium.
• Uses tanium_hat.main.Main.run_plugins() to call tanium_hat.plugin.Plugin.get_tanium_data() on every plugin
• Uses tanium_hat.main.Main.collect_tanium_results() to get the results of get_tanium_data for all plugins
• Uses tanium_hat.main.Main.write_csv() to write results to that_stats.csv in data_path
• Uses tanium_hat.main.Main.write_json_files() to write json pages from Tanium.

parse_config_analyze()[source]¶

Parse options that are only asked if the user supplied yes to analyze_data.

• Returns if analyze_data is False in tanium_hat.main.Main.PCONFIG
• Uses tanium_hat.options.ANALYZE to determine base options to search for/ask
• Uses tanium_hat.main.Main.load_layout_def() to load the python layout definition file as a module
• Uses tanium_hat.main.Main.load_layout_pptx() to load the PPTX file referenced in the python layout definition file

parse_config_base()[source]¶

Parse base options that are always asked.

• Uses tanium_hat.options.BASE to determine base options to search for/ask

parse_config_contents()[source]¶

Read the tanium_hat.main.Main.CONFIG dictionary for keys and prompt user for missing values.

• Sets tanium_hat.main.Main.PCONFIG with the output of tanium_hat.main.base_pconfig()
• Uses tanium_hat.main.Main.parse_config_base() to parse the config for base options
• Uses tanium_hat.main.Main.parse_config_plugins() to parse the config for plugin options
• Uses tanium_hat.main.Main.parse_config_analyze() to parse the config for analyze data options
• Uses tanium_hat.main.Main.parse_config_tanium() to parse the config for get tanium data options

parse_config_plugins()[source]¶

Parse options that are asked for plugins.

• Uses tanium_hat.main.Main.get_local_plugins() to load locally available plugins
• Uses tanium_hat.main.Main.get_enabled_plugins() to check which plugins get loaded
• Uses tanium_hat.main.Main.load_enabled_plugins() to load enabled plugins

parse_config_tanium()[source]¶

Parse options that are only asked if the user supplied yes to get_tanium_data.

• Returns if get_tanium_data is False in tanium_hat.main.Main.PCONFIG
• Uses tanium_hat.options.TANIUM to determine base options to search for/ask

pre_flight()[source]¶

Read configuration file and start file logging.

• Updates tanium_hat.main.Main.CONFIG with the dict parsed from tanium_hat.main.Main.CONFIG_FILE
• Uses tanium_hat.main.Main.add_file_logging() to setup file logging
• Uses tanium_hat.main.Main.parse_config_contents() to parse the configuration

register_zipper()[source]¶

Create a zip file of the data_path when python script exits.

• Uses tanium_kit.zipper.mkzip() to create a zip file of the data_path
• Uses atexit.register() to register the zipper function to run when this script reaches the end of execution (due to error or not)

run_plugin(mode, plugin_name, plugin_obj)[source]¶

Run a plugin using mode.

Parameters:	mode (str) – plugin mode to run, one of “get_tanium_data”, “get_internet_data”, “analyze_data” plugin_name (str) – name of plugin plugin_obj (tanium_hat.plugin.Plugin) – instantiated object of plugin class

run_plugins(mode)[source]¶

Run all plugins using mode.

• Uses tanium_hat.main.Main.sorted_plugins() to get a list of plugins sorted by priority order
• Uses tanium_hat.main.Main.run_plugin() to run the mode for for plugin

Parameters:	mode (str) – plugin mode to run, one of “get_tanium_data”, “get_internet_data”, “analyze_data”

save_file(out, filename, path, prompt=False, binary=False, **kwargs)[source]¶

Save a file in binary or text mode.

Parameters:	out (str) – The contents to write to the file filename (str) – The basename of the file to save path (str) – The path to save the file into prompt (bool, optional) – Default : False True: Prompt the user using tanium_kit.ask.ask() where they would like to save the file to, defaulting to path False: Use path as is binary (bool, optional) – Default : False True : use tanium_kit.tools.write_binary() to write a binary file False : use tanium_kit.tools.write_file() to write a text file
Returns:	file_path – The full path to the file that was saved
Return type:	str

signal_handler(signal, frame)[source]¶

Signal handler for trapping Control-C (SIGINT).

sorted_plugins(d=1000)[source]¶

Sort the plugins based on priority.

• Uses tanium_hat.plugin.Plugin.get_order() to get the plugin priority

Parameters:	d (int, optional) – default : 1000 priority to use for plugins if not defined
Returns:	ret – sorted items() from plugins in tanium_hat.main.Main.PCONFIG
Return type:	list

start(**kwargs)[source]¶

Main workflow entry point for THAT.

Parameters:	config_file (str, optional) – default: tanium_hat.constants.CONFIG_FILE_PATH path to configuration file to use for this instance

takeoff()[source]¶

Run the enabled modes against the enabled plugins.

track_items(name, obj, attr)[source]¶

Pull items from object and add them into this object by name.

Parameters:	name (str) – name to store items from attr in obj under this classes tracker obj (object) – object to get attr from attr (str) – attribute to get from obj and to store in this class

valid_tmpl_keys()[source]¶

Produce a list of valid template keys.

Returns:	ret – str containing CR delimited list of all valid template keys
Return type:	str

write_csv(results, path, **kwargs)[source]¶

Write a csv file.

• Uses tanium_kit.excel_writer.ExcelWriter to pre-parse a list of dicts for writing to CSV

Parameters:	results (list of dict) – list of dictionaries to write to the CSV file path (str) – path to write csv file to
Returns:	ret – list of dictionaries post-processing by ExcelWriter
Return type:	list of dict

write_file(path, out)[source]¶

Write a file.

• If path is not absolute, path is prepended with data_path from tanium_hat.main.Main.PCONFIG

Parameters:	path (str) – path of file to write out (str) – contents to write to file

write_json_files()[source]¶

Write JSON files to the data_path.

• Uses tanium_hat.main.Main.get_info_json() to fetch info.json
• Uses tanium_hat.main.Main.write_file() to write info.json to data_path
• For each module name and url in tanium_hat.constants.MODULE_JSON_ITEMS, get the json from the url using tanium_hat.main.Main.get_module_json(), and write the json using tanium_hat.main.Main.write_file() to data_path