util module - Platform - BlueCat Gateway - 24.3.3

Gateway Administration Guide

ft:locale
en-US
Product name
BlueCat Gateway
Version
24.3.3

Helper utilities for the BlueCat Python API. This collection of functions provide extra functionality a lot of API methods and workflows use.

class bluecat.util.CustomHTMLParser(search_tag)

Bases: html.parser.HTMLParser

Custom HTML parser to search for tags. Sets found_tag True if tag found

handle_endtag(tag)

handle_starttag(tag, attrs)

bluecat.util.autologin(get_autologin)

Performs autologin using provided function, which should return username and password. Logs out and cleans up the session after workflow endpoint is called. Warning: This decorator is intended for REST endpoints only and might not work if used against UI endpoints.

Parameters Description
get_autologin

a function to retrieve username and password for autologin.

bluecat.util.chunk(container, n)

Given an iterable container, divide and return chunks of size n.

Parameters Description
container (Union[list, tuple])

A List or tuple that needs to be chunked.

n (int)

Number of items in each chunk.

Return type: Iterator

Returns: Generator that yields chunks of items of size <= n.

bluecat.util.cidr_to_bin(cidr)

CIDR to binary

Return type: str

bluecat.util.cleanup_directory(root_dir, cur_dir)

Recursively delete directory cur_dir until reaching parent directory root_dir

Parameters Description
root_dir (str)

Parent directory to delete until

cur_dir (str)

Direct child or sub directory to analyze for deletion

bluecat.util.combine_filters(validators=None)

Generates a function with a list of validator functions.

Parameters Description
validators

a list of functions that take Entity object as only parameter and return bool

Returns: a function that combines validation of the validators taken in

bluecat.util.config_filter(config_ids=None)

A wrapped validator that returns a validator for filtering by configuration. Also an example of writing validators.

Parameters Description
config_ids (list)

a list of Configuration id, if None, return Entities with a Configuration

Returns: a validator function that if an Entity’s parent Configuration is in config_ids

bluecat.util.decrypt_key(encrypted_token, key=None)

Decrypts token using key, config.secret_key will be used, if not provided.

Return type: bytes

bluecat.util.decrypt_key_from_file(name=None, path='customizations/.secret', key=None)

Decrypt the file given in path and find the key associated with the given name. Returns the key if found, otherwise will throw a PortalException.

Parameters Description
name (str)

A human readable name for the desired key that was used in the encrypt_key_to_file method for the key. If no name is provided the method will return the entire unencrypted contents of the file.

path

The path (including the filename) where the encrypted file is stored.

key (Union[bytes, str, NoneType])

The secret token for decrypting the encrypted file. The default token for the Portal server will be used if nothing is provided. The token must be a URL-safe base64-encoded 32-byte string; config.secret_key will be used if key is not provided.

Returns: The found key as a string.

Note:

This function does not support the built-in workspace. For a consistent behaviour it is recommended to use bluecat.gateway.platform.Platform.decrypt_value_from_file instead.

Note:

This function will likely be deprecated in a future release.

bluecat.util.encrypt_key(token, key=None)

Encrypts token using key, config.secret_key will be used, if not provided.

Return type: bytes

bluecat.util.encrypt_key_to_file(token, name=None, path='customizations/.secret', key=None)

Encrypt the given name, token pair into a file specified by path. The token can later be retrieved using the name with the decrypt_key_from_file method. An optional token can be specified which is the secret used to encrypt the token and is required to decrypt it if a custom one was provided for this method.

Parameters Description
name (str)

A human readable name for the token that will be used in decrypt_key_from_file to retrieve the correct token. Cannot contain special characters such as “=”. If no name is provided the method will only write the encrypted password to the file. This will overwrite any other contents the file may have.

token (bytes)

Sensitive information to be encrypted such as a password.

path

The path (including the filename) where the encrypted file should be stored.

key (Union[bytes, str, NoneType])

The secret token used in the encryption process. This is necessary to decrypt the encrypted file and if provided should be stored securely and must not be shared. The token must be a URL-safe base64-encoded 32-byte string; config.secret_key will be used if key is not provided.

Returns: None

Note:

This function does not support the built-in workspace. For a consistent behaviour it is recommended to use bluecat.gateway.platform.Platform.encrypt_value_from_file instead.

Note:

This function will likely be deprecated in a future release.

bluecat.util.exception_catcher(func)

Catches uncaught exceptions inside workflow endpoints and flashes standardized message to user.

Parameters Description
func

function being wrapped, supplied by automatically as a python decorator.

Returns: redirect to home.

bluecat.util.filter_entities(entity_generator, filters=None)

Filter a generator of Entities with a list of filters with itertools.ifilter

Parameters Description
entity_generator (Iterator)

a generator of entity objects

filters (list)

a list of filters

Returns: an filtered iterator

bluecat.util.get_address_space_size(cidr, subnetwork_size)

Given a CIDR address, calculate the number of subnets given the number of addresses contained within a subnet.

Parameters Description
cidr (str)

CIDR Address e.g. (“10.0.0.0/16”)

subnetwork_size (int)

Number of addresses contained in each subnet

Return type: int

Returns: Number of adresses avaialble

bluecat.util.get_broadcast_network_address(cidr)

Return the broadcast and network address of a subnet

Parameters Description
cidr (str)

Network CIDR (e.g. 10.0.0.0/24)

Return type: dict

Returns: Network and broadcast address in JSON format

bluecat.util.get_configurations(default_val=False)

Get a list of configurations for display in a drop-down menu box.

Return type: list

Returns: List of configuration ID, configuration name tuples.

bluecat.util.get_password_from_file(password_path)

Extracting encoded password from file and with key that defined in configuration file.

Parameters Description
password_path_option

path to a password file.

Return type: str

Returns: password

Note:

This function does not support the built-in workspace. For a consistent behaviour it is recommended to use bluecat.gateway.platform.Platform.decrypt_value_from_file instead.

Note:

This function will likely be deprecated in a future release.

bluecat.util.get_portal_mongo_db()

Returns Database pointer

bluecat.util.get_text(workflow_dir, language)

Get text of given language from workflow_dir.

Return type: dict

Returns: Dictionary of text results.

bluecat.util.has_response(response)

Check for none response for anything that you would normally expect to return an entity.

Parameters Description
response

API response from BAM.

Return type: bool

Returns: True if response contains an object representing a valid found entity in BAM, otherwise False.

bluecat.util.int2ip4(addr)

Turn a 32-bit integer into an IPv4 address string.

Return type: str

bluecat.util.ip42int(addr)

Turn an IP address string into a 32-bit integer.

Return type: int

bluecat.util.is_valid_domain_name(address)

Verifies if provided string is a valid string to ba a domain name.

Return type: bool

bluecat.util.is_valid_ipv4_address(address)

Figure out if a string is a valid IPv4 address.

Return type: bool

bluecat.util.is_valid_ipv6_address(address)

Figure out if a string is a valid IPv6 address.

Return type: bool

bluecat.util.is_valid_netloc(netloc)

For given netlocation checks whether it is a valid IPv4 Address or IPv6 Address or Domain Name.

Parameters Description
netloc (str)

The IPv4 Address or IPv6 Address or Domain Name to be checked.

Return type: bool

Returns: True if it is a valid IPv4 Address or IPv6 Address or Domain Name and False otherwise.

bluecat.util.map_to_properties(properties)

Turn a dictionary of properties into a BAM property string.

Return type: str

bluecat.util.no_cache(func)

Force browser to not cache wrapped view and reload it every time.

Parameters Description
func

The wrapped view.

Returns: Decorated function.

bluecat.util.parse_netloc(url)

From given url parse out the domain or IP address of the URL.

Parameters Description
url (str)

The URL to parse.

Return type: str

Returns: IP address or domain name as a string, empty string if parsing failed.

bluecat.util.parse_properties(properties)

Parses property input that is in a list or dictionary form and converts it to a string of property=value separated by ‘|’ pipe characters

Parameters Description
properties (str)

list or dictionary containing properties.

Return type: str

Returns: properties in form of a string with property=value separated by ‘|’ pipe characters format.

bluecat.util.properties_to_map(properties)

Turn a string of BAM properties into a dictionary of name->value.

Param:

properties: string in the form ‘a=b|c=d|…’

Return type: dict

Returns: a dictionary with parsed properties.

bluecat.util.remove_from_bam_control(ip, username='', password='', sleep=False)

Not Tested! Removes a BDDS from BAM control

Parameters Description
username (str)

The administrator username of the BDDS.

password (str)

The administrator password of the BDDS.

ip (str)

IP address of the BDDS.

sleep (bool)

Boolean to give BDDS time to recover after the operation.

Return type: bool

Returns: False if there is an error removing from control. True otherwise.

bluecat.util.rest_exception_catcher(func)

Catches uncaught exceptions inside workflow endpoints and raises 500 HTTP error with standardized message.

Parameters Description
func

function being wrapped, supplied by automatically as a python decorator.

Returns: HTTP error.

bluecat.util.rest_workflow_permission_required(workflow)

Checks that the user has permission for the view that was called. Returns a 401 to the user if they do not have permission.

Parameters Description
workflow

The name of the workflow the view is in and that permission was set for.

bluecat.util.run_ssh_cmd(hostname, username='', password='', cmd='', timeout=30, **kwargs)

Execute a single SSH command.

Parameters Description
hostname (str)

Hostname or IPv4/IPv6 address of the remote server.

username (str)

Username to login to remote server if no key found.

password (str)

Password to login to remote server if no key found.

cmd (str)

One-liner command to execute on remote system via SSH.

timeout (int)

Time to wait for command to execute.

kwargs

Additional keyword arguments supported by paramiko.SSHClient.connect().

Return type: tuple

Returns: A tuple: stdout, stderr.

bluecat.util.safe_str(obj)

Return the byte string representation of obj

bluecat.util.setup_mongo_db()

Configure parameters for MongoDB, and prepare Database pointer

bluecat.util.ui_secure_endpoint(func)

UI security response headers attached to browser’s response

Parameters Description
func

The wrapped view.

Returns: Decorated function.

bluecat.util.validate_partial_ipv4_address(address)

Check if provided string is a valid partial IPv4 address

Return type: bool

bluecat.util.workflow_permission_required(workflow)

Checks that the user has permission for the view that was called. Returns user to home if they do not have permission.

Parameters Description
workflow

The name of the workflow the view is in and that permission was set for.

Returns: The generated function decorator.