rho package

Submodules

rho.ansible_utils module

Utilities for wrapping Ansible.

exception rho.ansible_utils.AnsibleProcessException

Bases: Exception

Exception raised when an Ansible process fails.

exception rho.ansible_utils.AnsibleTimeoutException

Bases: Exception

Exception raised when an Ansible process times out.

rho.ansible_utils.auth_as_ansible_host_vars(auth)

Get the Ansible host vars that implement an auth.

Parameters:auth – the auth. A dictionary with fields ‘id’, ‘name’, ‘username’, ‘password’, and ‘ssh_key_file’. Returns:a dict that can be used as the host variables in an Ansible inventory.

rho.ansible_utils.log_yaml_inventory(label, inventory)

Log yaml inventory but mask passwords

Parameters:inventory – A dictionary of the ansible inventory

rho.ansible_utils.redact_dict(redact_key_list, a_dict)

Redact_values in a dictionary

Parameters:

• redact_key_list – keys in dictionary that value should be redacted
• a_dict – A dictionary to redact

Returns:

the redacted dictionary

rho.ansible_utils.run_with_vault(cmd_string, vault_pass, env=None, log_path=None, log_to_stdout=None, log_to_stdout_env=None, ansible_verbosity=0, timeout=None, print_before_run=False, error_on_failure=True)

Runs ansible command allowing for password to be provided after process triggered.

Returns after the process completes.

Parameters:

• cmd_string – the command to run.
• vault_pass – the password to the user’s Ansible Vault.
• env – the environment to run the subprocess in.
• log_path – a path to write the process’s log to. Defaults to ‘XDG_DATA_HOME/rho/ansible_log’.
• log_to_stdout – if not None, write Ansible’s log to stdout using the provided function as a filter. Defaults to None.
• log_to_stdout_env – a dictionary of environment variables
• ansible_verbosity – the number of v’s of Ansible verbosity.
• timeout – timeout, in seconds, for the called process.
• print_before_run – if true, print the command string before running it. Defaults to False.

Returns:

the popen.spawn object for the process.

rho.authaddcommand module

AuthAddCommand is used to add authentication credentials for system access

class rho.authaddcommand.AuthAddCommand

Bases: rho.clicommand.CliCommand

This command is for creating new auths which can be later associated with profiles to gather facts.

rho.authaddcommand.auth_exists(cred_list, auth_name)

Checks whether authentication credential already exists

Parameters:

• cred_list – A list of credential dictionaries
• auth_name – Name of credential to check for existence

Returns:

True if auth_name exists, False otherwise

rho.authaddcommand.make_auth_for_options(options)

Construct the OrderedDict auth given our options.

Parameters:options – an options object, from optparse Returns:an OrderedDict representing the auth being added

rho.authclearcommand module

AuthClearCommand is for removing a specific or all existing authentication credentials.

class rho.authclearcommand.AuthClearCommand

Bases: rho.clicommand.CliCommand

This command is for removing a specific or all existing auths.

rho.autheditcommand module

AuthEditCommand is used to edit existing authentication credentials for system access

class rho.autheditcommand.AuthEditCommand

Bases: rho.clicommand.CliCommand

This command is fpr editing the auths already existing. The user can edit the username, password and ssh key file path.

rho.autheditcommand.optional_arg(arg_default)

Call back function for arg-parse for when arguments are optional

Parameters:arg_default – The default for the argument Returns:Function for handling the argument

rho.authlistcommand module

AuthListCommand is used to list authentication credentials for system access

class rho.authlistcommand.AuthListCommand

Bases: rho.clicommand.CliCommand

This command is for displaying all existing auths. Passwords are encrypted in the console.

rho.authshowcommand module

AuthShowCommand is used to display existing authentication credentials

class rho.authshowcommand.AuthShowCommand

Bases: rho.clicommand.CliCommand

This command is for displaying an existing auth requested. Passwords are encrypted in the console.

rho.cli module

Rho Command Line Interface

class rho.cli.CLI

Bases: object

Class responsible for displaying ussage or matching inputs to the valid set of commands supported by rho.

main()

Method determine whether to display usage or pass input to find the best command match. If no match is found the usage is displayed

rho.clicommand module

Base CLI Command Class

class rho.clicommand.CliCommand(name='cli', usage=None, shortdesc=None, description=None)

Bases: object

Base class for all sub-commands.

main()

The method that does a basic check for command validity and set’s the process in motion.

rho.facthashcommand module

Hash sensitive facts.

class rho.facthashcommand.FactHashCommand

Bases: rho.clicommand.CliCommand

Hash sensitive facts.

read_and_hash(path)

Read the given CSV file and hash the prescribed facts :param path: The csv file to read :returns: The keys (set) and data (dict) composing the csv file

rho.facthashcommand.compute_sha256_hash(input_string)

Computes the sha256 hash for a string :param input_string: The string to hash :returns: The hex hash value

rho.factlistcommand module

List available facts.

class rho.factlistcommand.FactListCommand

Bases: rho.clicommand.CliCommand

List available facts.

rho.facts module

Defining the set of facts that Rho can scan for.

rho.facts.expand_facts(fact_names)

Expand a list of facts with implicit facts and short names.

Parameters:fact_names – a list of fact names Returns:a set of facts to collect

rho.facts.new_fact(fact_name, description, is_default=None, is_sensitive=False, always_collect=False, categories=None)

Define a new fact.

Parameters:

• fact_name – the name of the fact.
• description – a short description of the fact, for ‘rho fact list’ and the documentation.
• is_default – whether this fact should be scanned for by default.
• is_sensitive – whether this fact should be redacted by ‘rho fact hash’.
• always_collect – whether rho should always collect this fact.

rho.host_discovery module

Discover hosts on a network.

rho.host_discovery.create_ping_inventory(vault, vault_pass, profile_ranges, profile_port, credential, forks, ansible_verbosity)

Find which auths work with which hosts.

Parameters:

• vault – a Vault object
• vault_pass – password for the Vault?
• profile_ranges – hosts for the profile
• profile_port – the SSH port to use
• credential – auth to use
• forks – the number of Ansible forks to use

Returns:

a tuple of (list of IP addresses that worked for any auth,

map from host IPs to SSH ports that worked with them, map from host IPs to lists of auths that worked with them

)

rho.host_discovery.process_ping_output(out_lines)

Find successful hosts from the output of a ping command.

Use this function by using ansible to run echo “Hello” on remote hosts, then sending the output to this function.

Parameters:out_lines – an iterator returning lines of Ansible output. Returns:the hosts that pinged successfully, as a set and those that failed, as a set.

rho.inventory_scan module

Scan for software on hosts in an inventory.

rho.inventory_scan.create_main_inventory(vault, hosts, port_map, auth_map, path)

Write an inventory file given the results of host discovery.

Parameters:

• vault – an Ansible vault to encrypt the results.
• hosts – a list of hosts in the inventory.
• port_map – a mapping from hosts to SSH port numbers.
• auth_map – a mapping from hosts to SSH credentials.
• path – the path to write the inventory.

rho.inventory_scan.hosts_by_group(yml_dict)

Get the hosts in each group from an inventory YAML file.

Note: this works on inventory files written by create_main_inventory, but not on any Ansible inventory file.

Parameters:yml_dict – the Ansible inventory file, as a Python dict. Returns:a dict of the form {‘group name’: [‘host1’, ‘host2’, …],

… }

rho.inventory_scan.inventory_scan(hosts_yml_path, facts_to_collect, report_path, vault_pass, base_name, forks=None, scan_dirs=None, log_path=None, verbosity=0)

Run an inventory scan.

Parameters:

• hosts_yml_path – path to an Ansible inventory file to scan.
• facts_to_collect – a list of facts to collect.
• report_path – the path to write a report to.
• vault_pass – the vault password used to protect user data
• base_name – the base name of the output files
• forks – the number of Ansible forks, or None for default.
• scan_dirs – the directories on the remote host to scan, or None for default.
• log_path – path to log to, or None for default.
• verbosity – number of v’s of Ansible verbosity.

Returns:

True if scan completed successfully, False if not.

rho.inventory_scan.make_inventory_dict(hosts, port_map, auth_map, group_size=10)

Make the inventory for the scan, as a dict.

Parameters:

• hosts – a list of hosts for the inventory
• port_map – mapping from hosts to SSH ports
• auth_map – map from host IP to a list of auths it works with
• group_size – write hosts in groups of this size

Returns:

a dict with the structure:

{'group1':
     {'hosts':
         {'IP address 1': {'host-vars-1'},
          'IP address 2': {'host-vars-2'},
          # ...
         }
     },
 'group2':
     {'hosts':
          ....
     },
 ....
}

rho.inventory_scan.process_host_vars(facts_to_collect, vars_by_host)

Process Ansible output into output facts.

Parameters:

• facts_to_collect – list of facts to collect.
• vars_by_host – dictionary (host: facts dictionary)

Returns:

list of per host fact dicitionaries

rho.inventory_scan.write_fact_report(facts_to_collect, facts_out, report_path)

Write fact report.

Parameters:

• facts_to_collect – The set of facts to output in the report
• facts_out – list of per host fact dicitionaries
• report_path – The path to output the report

rho.postprocessing module

Postprocessing for facts coming from our Ansible playbook.

class rho.postprocessing.PkgInfo(row, separator)

Bases: object

This is an inner class for RedhatPackagesRhoCmd class and provides functionality to parse the results of running the (only) command string named ‘get_package_info’. This is purely to make the parsing cleaner and understandable.

RED_HAT_KEYS = ('199e2f91fd431d51', '5326810137017186', '45689c882fa658e0', '219180cddb42a60e', '7514f77d8366b0d9', '45689c882fa658e0')

details()

Provides package details including name, version and release. :returns: String including name, version and release

details_built()

Provides information on when the package was built :returns: String including details and build date

details_install()

Provides information on when the package was installed. :returns: String including installation date

is_gpg_red_hat_pkg()

Determines if package is a Red Hat package with known GPG key. :returns: True if Red Hat, False otherwise

exception rho.postprocessing.PkgInfoParseException

Bases: BaseException

Defining an exception for failing to parse package information

rho.postprocessing.classify_kie_file(pathname)

Classify a kie-api-* file.

Parameters:pathname – the path to the file Returns:a BRMS version string, or None if not a Red Hat kie file.

rho.postprocessing.classify_releases(lines, classifications)

Classify release strings using a dictionary.

rho.postprocessing.determine_pkg_facts(rh_packages)

Gets the last installed and last build packages from the list

Parameters:rh_packages – the filtered list of red hat packages Returns:tuple of last installed and last built

rho.postprocessing.encode_and_join(join_char, list_of_strings)

Create a list of utf-8 encoded strings and join them.

Parameters:

• join_char – The character to join on
• list_of_strings – Strings to encode and join

Returns:

joined encoded string

rho.postprocessing.escape_characters(data)

Processes input data values and strips out any newlines or commas

rho.postprocessing.generate_eap_summary(facts_to_collect, facts)

Generate a single summary fact about whether the machine has EAP.

rho.postprocessing.generate_fuse_summary(facts_to_collect, facts)

Generate a single summary fact about whether the machine has Fuse.

rho.postprocessing.handle_redhat_packages(facts, data)

Process the output of redhat-packages.results and supply the appropriate output information

rho.postprocessing.handle_systemid(fact_names, data)

Process the output of systemid.contents and supply the appropriate output information

rho.postprocessing.process_addon_versions(fact_names, host_vars)

Classify release strings for JBoss BRMS and FUSE.

Parameters:

• fact_names – the set of fact names that the user requested.
• host_vars – the host vars from Ansible.

Returns:

a dict of key-value pairs to output.

rho.postprocessing.process_brms_output(fact_names, host_vars)

Process facts for jboss.brms.

rho.postprocessing.process_cat_results(filename, cat_out)

Process the output of a with_items cat from Ansible.

rho.postprocessing.process_find_jboss_modules_jar(fact_names, host_vars)

Process the output of ‘find jboss-modules.jar’

rho.postprocessing.process_find_karaf_jar(fact_names, host_vars)

Process the output of ‘find karaf.jar’

rho.postprocessing.process_fuse_init_files(fact_names, host_vars)

Process facts for jboss.fuse.init-files

Note: these facts are included because they can be useful, but the filters are very susceptible to letting through lines which a human could easily tell are false positives, but we don’t handle that automatically.

rho.postprocessing.process_fuse_on_eap(fact_names, host_vars)

Find JBoss Fuse when it is layered on top of JBoss EAP.

rho.postprocessing.process_id_u_jboss(fact_names, host_vars)

Process the output from ‘id -u jboss’, as run by Ansible

Returns:a dict of key-value pairs to add to the output.

rho.postprocessing.process_indicator_files(indicator_files, ls_out)

Process the output of a with_items ls from Ansible.

rho.postprocessing.process_jboss_eap_common_files(fact_names, host_vars)

Process the output of ‘test -e <dir>’, for common install paths.

Returns:a dict of key, value pairs to add to the output.

rho.postprocessing.process_jboss_eap_home(fact_names, host_vars)

Find the EAP_HOME directory of a JBoss installation, if possible.

rho.postprocessing.process_jboss_eap_init_files(fact_names, host_vars)

Look for jboss and EAP in init system output.

Returns:a dict of key, value pairs to add to the output.

rho.postprocessing.process_jboss_eap_locate(fact_names, host_vars)

Process the results of ‘locate jboss-modules.jar’.

Returns:a dict of key, value pairs to add to the output.

rho.postprocessing.process_jboss_eap_packages(fact_names, host_vars)

Process the list of JBoss EAP-related RPMs.

Returns:a dict of key, value pairs to add to the output.

rho.postprocessing.process_jboss_eap_processes(fact_names, host_vars)

Process the output of ‘ps -A -f e | grep eap’

Returns:a dict of key, value pairs to add to the output.

rho.postprocessing.process_jboss_versions(fact_names, host_vars)

Get JBoss version information from the host_vars.

Parameters:

• fact_names – the set of fact names the user requested.
• host_vars – the host vars from Ansible.

Returns:

a dict of key-value pairs to output.

rho.postprocessing.process_karaf_home(fact_names, host_vars)

Process karaf_home indicators to detect Fuse-on-Karaf.

rho.postprocessing.raw_output_present(fact_names, host_vars, this_fact, this_var, command)

Basic sanity checks for processing an Ansible raw command.

Parameters:

• fact_names – the facts to be collected
• host_vars – all variables collected for a host
• this_fact – the name of the fact we are processing
• this_var – the name that Ansible has for our output
• command – the command that was run

Returns:

a tuple of (None or error dict, None or raw command output). The error dict is suitable for inclusion in the rho output dictionary. There will not be both errors and raw command output. If raw command output is returned, it will have fields ‘rc’ and ‘stdout_lines’ or ‘results’.

Usage:

err, output = raw_output_present(…) if err is not None:

return err

… process output …

rho.profileaddcommand module

ProfileAddCommand is used to create profiles that associate hosts and authentication credentials

class rho.profileaddcommand.ProfileAddCommand

Bases: rho.clicommand.CliCommand

This command is for creating new profiles based on hosts and the auths the user wants to associate.

rho.profileaddcommand.profile_exists(profile_list, profile_name)

Checks whether a network profile already exists

Parameters:

• profile_list – A list of profile dictionaries
• profile_name – Name of a network profile to check for existence

Returns:

True if profile_name exists, False otherwise

rho.profileclearcommand module

ProfileClearCommand is used to clear profiles that already existing either individually or all profiles

class rho.profileclearcommand.ProfileClearCommand

Bases: rho.clicommand.CliCommand

This command is for removing profiles. A user can remove an existing profile by passing in the name or ask to delete all profiles.

rho.profileeditcommand module

ProfileEditCommand is used to edit existing profiles that associate hosts and authentication credentials

class rho.profileeditcommand.ProfileEditCommand

Bases: rho.clicommand.CliCommand

This command is for editing an existing profile. The name of the profile has to be supplied. The hosts, auths attached or both can be changed.

rho.profilelistcommand module

ProfileListCommand is used to list existing profiles that associate hosts and authentication credentials

class rho.profilelistcommand.ProfileListCommand

Bases: rho.clicommand.CliCommand

This command is for displaying all existing profiles the user has added previously.

rho.profileshowcommand module

ProfileShowCommand is used to show a specific profiles that associate hosts and authentication credentials

class rho.profileshowcommand.ProfileShowCommand

Bases: rho.clicommand.CliCommand

This command is for displaying a particular profile the user has added previously if it has not been deleted already.

rho.scancommand module

Rho CLI Commands

class rho.scancommand.ScanCommand

Bases: rho.clicommand.CliCommand

The command that performs the scanning and collection of facts by making the playbook, inventory and running ansible.

rho.scancommand.redacted_auth_string(auth)

Format an auth for the host auth mapping file.

Parameters:auth – the auth. A dictionary with fields ‘id’, ‘name’, ‘username’, ‘password’, and ‘ssh_key_file’. Returns:a string of the form ‘name, username, ****, ssh_key_file’

rho.translation module

Rho Translation initalization utility

rho.utilities module

A set of reusable methods common to many of the commands

exception rho.utilities.NotCIDRException

Bases: Exception

Exception for when a string does not look like a CIDR range.

rho.utilities.check_path_validity(path_list)

Given a list of paths it verifies that all paths are valid absolute path inputs for a scoped scan. If not it return a list of invalid paths.

Parameters:path_list – list of paths to validate Returns:empty list or list of invalid paths

rho.utilities.cidr_to_ansible(ip_range)

Convert an IP address range from CIDR to Ansible notation.

Parameters:ip_range – the IP range, as a string Returns:the IP range, as an Ansible-formatted string Raises:NotCIDRException – if ip_range doesn’t look similar to CIDR notation. If it does look like CIDR but isn’t quite right, print out error messages and exit.

rho.utilities.ensure_config_dir_exists()

Ensure the Rho configuration directory exists.

rho.utilities.ensure_data_dir_exists()

Ensure the Rho data directory exists.

rho.utilities.get_config_path(filename)

Provides the path for a configuration filename

Parameters:filename – The filename to return the config path for Returns:path to for filename in XDG_CONFIG_HOME associated with rho

rho.utilities.is_stringlike(obj)

Check if an object is a string.

This function is for Python 2 and 3 compatibility.

rho.utilities.iteritems(dictionary)

Iterate over a dictionary’s (key, value) pairs using Python 2 or 3.

Parameters:dictionary – the dictionary to iterate over.

rho.utilities.multi_arg(option, opt_str, value, parser)

Call back function for arg-parse for when arguments are multiple

Parameters:

• option – The option
• opt_str – The option string
• value – The value
• parser – The parser for handling the option

rho.utilities.process_discovery_scan(line)

Process the output of a discovery scan.

Parameters:line – a line from the discovery scan_log

rho.utilities.process_host_scan(line)

Process the output of a discovery scan.

Parameters:line – a line from the discovery scan_log

rho.utilities.read_ranges(ranges_or_path)

Process a range list from the user.

This function reads a hosts file if necessary, validates that all IP ranges are in Ansible format, and rewrites CIDR address ranges to Ansible format if necessary.

Parameters:ranges_or_path – either a list of IP address ranges or a one-element list where the one element is the path of a file with ranges. Returns:list of IP address ranges in Ansible format

rho.utilities.setup_logging(verbosity)

Set up Python logging for Rho.

Must be run after ensure_data_dir_exists().

Parameters:verbosity – verbosity level, as measured in -v’s on the command line. Can be None for default.

rho.utilities.str_to_ascii(in_string)

Coverts unicode string to ascii string

Parameters:in_string – input string to convert to ascii Returns:ASCII encoded string

rho.utilities.strip_prefix(string, prefix)

Remove a prefix from a string, if present.

Parameters:

• string – the string to operate on.
• prefix – the prefix to remove.

Returns:

string without prefix, if prefix was present.

rho.utilities.strip_suffix(string, suffix)

Remove a suffix from a string, if present.

Parameters:

• string – the string to operate on.
• suffix – the suffix to remove.

Returns:

string without suffix, if suffix was present.

rho.utilities.tail_log(path, ansible_verbosity, process_output, env=None)

Follow and provide host scan output

Parameters:

• path – tuple containing the path to file to follow
• ansible_verbosity – the verbosity level
• process_output – the method to process the output
• env – the enviroment to add to tail process

rho.utilities.validate_port(arg)

Check that arg is a valid port.

Parameters:arg – either a string or an integer. Returns:The arg, as an integer. Raises:ValueError, if arg is not a valid port.

rho.utilities.write_csv_data(keys, data, path)

Write csv data with input fieldnames a dictionary of data and the file path to write to.

Parameters:

• keys – The field names and keys of the dictionary
• data – The dictionary of data to convert to csv
• path – The file path to write to

rho.vault module

Vault is used to read and write data securely using the Ansible vault

class rho.vault.Vault(password)

Bases: object

R/W an ansible-vault file

dump_as_json(obj, stream)

Convert object to json and encrypt the data.

Parameters:

• obj – Python object to convert to json
• stream – The location to write the encrypted data to. If this is a file in Python 3, it must be open in binary mode.

dump_as_json_to_file(obj, file_path)

Convert object to json and encrypt the data.

Parameters:

• obj – Python object to convert to json
• file_path – The file to write data to via temp file

dump_as_yaml(obj, stream)

Convert object to yaml and encrypt the data.

Parameters:

• obj – Python object to convert to yaml
• stream – The location to write the encrypted data to.

dump_as_yaml_to_file(obj, file_path)

Convert object to yaml and encrypt the data.

Parameters:

• obj – Python object to convert to yaml
• file_path – The file to write data to via temp file

dump_to_stream(data, stream)

Encrypt data and write to stream

Parameters:

• data – The information to be encrypted
• stream – If not None the location to write the encrypted data to.

load(stream)

Read vault steam and return python object

Parameters:stream – The stream to read data from Returns:The decrypted data

load_as_json(secure_file)

Read vault secured file and return json decoded object

Parameters:secure_file – The file to read data from as json Returns:The JSON data

load_as_yaml(secure_file)

Read vault secured file and return YAML decoded object

Parameters:secure_file – The file to read data from as yaml Returns:The YAML data

load_secure_file(secure_file)

Read vault secured file and return python object

Parameters:secure_file – The file to read data from Returns:The decrpted data

rho.vault.get_vault(vaultfile=None, prompt='Please enter your rho vault password: ')

Helper method that will get the vault password via input file or from standard input and then initialize a vault for users

Parameters:vaultfile – The location of a file with the vault password Returns:An initialized vault

rho.vault.get_vault_and_password(vaultfile=None, prompt='Please enter your rho vault password: ')

Helper method that will get the vault password via input file or from standard input and then initialize a vault for users

Parameters:vaultfile – The location of a file with the vault password Returns:An initialized vault and the password

rho.vault.get_vault_password(prompt='Please enter your rho vault password: ')

Requests the users password from the command line

rho.vault.read_vault_password(vault_password_file)

Reads vault password from file for scripting

Parameters:vault_password_file – Path to vault password file Returns:vault password string

rho.vault.represent_none(self, _)

Render None with nothing in yaml string when dumped

Module contents