API Reference

CLI Management

module:bastio.cli synopsis:A module responsible for the CLI of the agent. author:Amr Ali <amr@databracket.com>

class bastio.cli.CommandLine

Parse and logically validate command line argments.

parse()

Parse and validate arguments from the command line and set global configurations.

bastio.cli.bastio_main()

Main application entry point.

SSH And Communication Management

module:bastio.ssh synopsis:A Package for SSH management and communication. author:Amr Ali <amr@databracket.com>

Backend Connection Management

module:bastio.ssh.client synopsis:A module for SSH client implementations. author:Amr Ali <amr@databracket.com>

class bastio.ssh.client.BackendConnector

A singleton to establish and maintain a secure connection with the backend over a specific subsystem channel. This connector supports registering of endpoints where processors can register their endpoint to communicate with the backend. It is guaranteed that the messages will be delivered ASAP but the actual ETA is chaotic.

class EndPoint

EndPoint(ingress, egress)

egress

Alias for field number 1

ingress

Alias for field number 0

BackendConnector.close()

Close open channels and transport.

BackendConnector.is_active()

Check whether the transport is still active.

BackendConnector.register(endpoint)

Register an endpoint to this connector to so that it can communicate with the backend. The endpoint is a tuple of one ingress queue as first argument and egress as the second argument.

Parameters:endpoint (BackendConnector.EndPoint) – A tuple of two queues; ingress and egress.

BackendConnector.start()

Start the connection handler thread.

BackendConnector.stop()

Stop the connection handler thread.

Action Processor

module:bastio.ssh.api synopsis:A module responsible for the API between the backend and the agent. author:Amr Ali <amr@databracket.com>

class bastio.ssh.api.Processor

A class to handle action messages coming from the backend and send back a feedback to indicate success or failure of the action requested. This class is a kind-singleton which means you cannot instantiate more than one copy per application life time.

endpoint()

Return an ingress and an egress points to communicate with this processor.

Returns:bastio.ssh.client.BackendConnector.EndPoint

process(message)

Process a message and return a feedback.

Parameters:message (A subclass of bastio.ssh.protocol.ActionMessage) – A message to be processed. Returns:bastio.ssh.protocol.FeedbackMessage

stop()

Signal the action handler to stop.

Protocol Parsing And Logic Routing

module:bastio.ssh.protocol synopsis:A module containing protocol messages. author:Amr Ali <amr@databracket.com>

Low Level Protocols

class bastio.ssh.protocol.Netstring(sock, limit=32)

A class to help parsing and composing Netstring formatted messages.

This class takes a sock and an optional message length limit argument through its constructor for operating on data as it is received. The limit parameter is in KiB, so passing limit=32 means that the message length limit will be 32768 bytes. The socket passed must return a zero-sized string as an indication of EOF.

There are two class methods, compose to compose Netstring formatted messages and parse to parse Netstring messages.

classmethod compose(data)

Compose a Netstring formatted message.

Parameters:data (str) – The data to be wrapped in a Netstring message. Returns:A Netstring formatted message for the data passed in.

classmethod parse(string)

Parse a Netstring message and return the result.

Parameters:string (str) – The Netstring message to be parsed. Returns:The result of parsing the Netstring message.

recv()

Receive a single Netstring message from the socket.

Returns:The result of parsing a single Netstring message.

Message Bases

class bastio.ssh.protocol.ProtocolMessage(mid=None, **kwargs)

A protocol message base class.

classmethod parse(obj, traverse=True)

Check protocol message fields and validate them.

Return a new object of type cls containing the validated feedback object.

Parameters:

• obj (bastio.mixin.Json) – A JSON object containing the relevant fields for this protocol message.
• traverse (bool) – Whether to traverse parse on all the classes in the hierarchy.

Returns:

A new object of type cls containing the validated protocol message object.

reply(feedback, status)

Reply to a specific message with a feedback message that has the same MID.

Parameters:

• feedback (str) – The feedback message string.
• status (int) – The status of the feedback message.

Returns:

FeedbackMessage

class bastio.ssh.protocol.ActionMessage(username, **kwargs)

A protocol action message base class. Use this class as a base for all other action messages.

classmethod parse(obj, traverse=True)

Check action message fields and validate them.

Return a new object of type cls containing the validated action object.

Parameters:

• obj (bastio.mixin.Json) – A JSON object containing the relevant fields for this action message.
• traverse (bool) – Whether to traverse parse on all the classes in the hierarchy.

Returns:

A new object of type cls containing the validated action object.

Message Parsers

class bastio.ssh.protocol.MessageParser

A protocol message parser for JSON strings.

Note that this class acts as a router for the type of messages you can handle, so in order to add support for another message you will have to edit the class dictionary SupportedMessages to include the message type you wish to support.

classmethod parse(json_string)

Parse a JSON string and return the relevant object that represents the type of this message.

Parameters:json_string (str) – The JSON string for a message. Returns:An object that represents this message type.

class bastio.ssh.protocol.ActionParser

A protocol action message parser.

Note that this class acts as a router for the actions that you can carry out, so in order to add support for a particular action you will have to edit the class dictionary SupportedActions to include the action type you wish to support.

classmethod parse(obj)

Parse an action-type and return the relevant action object that represents the action-type of this message.

Parameters:obj (bastio.mixin.Json) – A JSON object for an action. Returns:A parsed and validated action message.

Protocol Messages

class bastio.ssh.protocol.FeedbackMessage(feedback, status, **kwargs)

A protocol feedback message.

classmethod parse(obj, traverse=True)

Check feedback message fields and validate them.

Return a new object of type cls containing the validated feedback object.

Parameters:

• obj (bastio.mixin.Json) – A JSON object containing the relevant fields for this feedback message.
• traverse (bool) – Whether to traverse parse on all the classes in the hierarchy.

Returns:

A new object of type cls containing the validated feedback object.

class bastio.ssh.protocol.AddUserMessage(sudo, **kwargs)

An add-user action message.

classmethod parse(obj, traverse=True)

Check add-user message fields and validate them.

Return a new object of type cls containing the validated action object.

Parameters:

• obj (bastio.mixin.Json) – A JSON object containing the relevant fields for this action message.
• traverse (bool) – Whether to traverse parse on all the classes in the hierarchy.

Returns:

A new object of type cls containing the validated action object.

class bastio.ssh.protocol.RemoveUserMessage(**kwargs)

A remove-user action message.

classmethod parse(obj, traverse=True)

Check remove-user message fields and validate them.

Return a new object of type cls containing the validated action object.

Parameters:

• obj (bastio.mixin.Json) – A JSON object containing the relevant fields for this action message.
• traverse (bool) – Whether to traverse parse on all the classes in the hierarchy.

Returns:

A new object of type cls containing the validated action object.

class bastio.ssh.protocol.UpdateUserMessage(sudo, **kwargs)

A update-user action message.

classmethod parse(obj, traverse=True)

Check update-user message fields and validate them.

Return a new object of type cls containing the validated action object.

Parameters:

• obj (bastio.mixin.Json) – A JSON object containing the relevant fields for this action message.
• traverse (bool) – Whether to traverse parse on all the classes in the hierarchy.

Returns:

A new object of type cls containing the validated action object.

class bastio.ssh.protocol.AddKeyMessage(public_key, **kwargs)

A add-key action message.

classmethod parse(obj, traverse=True)

Check add-key message fields and validate them.

Return a new object of type cls containing the validated action object.

Parameters:

• obj (bastio.mixin.Json) – A JSON object containing the relevant fields for this action message.
• traverse (bool) – Whether to traverse parse on all the classes in the hierarchy.

Returns:

A new object of type cls containing the validated action object.

class bastio.ssh.protocol.RemoveKeyMessage(public_key, **kwargs)

A remove-key action message.

classmethod parse(obj, traverse=True)

Check remove-key message fields and validate them.

Return a new object of type cls containing the validated action object.

Parameters:

• obj (bastio.mixin.Json) – A JSON object containing the relevant fields for this action message.
• traverse (bool) – Whether to traverse parse on all the classes in the hierarchy.

Returns:

A new object of type cls containing the validated action object.

Cryptographic Utilities

module:bastio.ssh.crypto synopsis:A module for miscellaneous cryptographic facilities. author:Amr Ali <amr@databracket.com>

class bastio.ssh.crypto.RSAKey(msg=None, data=None, filename=None, password=None, vals=None, file_obj=None)

A class to add a few helper functions to paramiko.RSAKey.

classmethod from_public_key(public_key)

Load an instance of this class with public_key.

Parameters:public_key (str) – An OpenSSH formatted public key. Returns:RSAKey

classmethod generate(size)

A wrapper around paramiko’s RSAKey generation interface to add this class’s methods to it.

Parameters:size (int) – The size of the RSA key pair in bits you wish to generate. Returns:RSAKey

get_private_key()

Return private key data in PEM format.

get_public_key()

Return the public key in OpenSSH authorized_keys line format.

classmethod validate_private_key(data)

Validate private key data.

Parameters:data (str) – A PEM formatted private key content. Returns:Whether the key data is valid.

classmethod validate_private_key_file(filename)

Validate private key file.

Parameters:filename (str) – A filename that contains PEM formatted private key data. Returns:Whether the key file is valid.

classmethod validate_public_key(data)

Validate public key data.

Parameters:data (str) – An OpenSSH formatted public key. [ssh-][ALGO][ ][BASE64][ ][COMMENT] Returns:Whether the key data is valid.

Account Operations

module:bastio.account synopsis:A module responsible for communicating account details. author:Amr Ali <amr@databracket.com>

bastio.account.download_backend_hostkey()

Get Bastio’s backend SSH host key.

Returns:bastio.ssh.crypto.RSAKey Raises :bastio.excepts.BastioAccountError

bastio.account.upload_public_key(api_key, public_key, old_public_key=None)

Upload agent’s public key to Bastio on the account specified by api_key.

This action will create a new server when old_public_key is not specified and it is the first time we see this public_key. However the public key we store that identifies this server will be replaced IFF we already have old_public_key in our records and public_key does not exist in our database.

Parameters:

• api_key (str) – The API key for the Bastio account.
• public_key (The string output of bastio.ssh.crypto.RSAKey.get_public_key().) – The agent’s public key to be uploaded to Bastio’s servers.
• old_public_key (The string output of bastio.ssh.crypto.RSAKey.get_public_key().) – The agent’s old public key to be replaced by a new one.

Raises :

bastio.excepts.BastioAccountError

Configuration Utilities

module:bastio.configs synopsis:Configurations memory and file system store. author:Amr Ali <amr@databracket.com>

class bastio.configs.GlobalConfigStore(section='agent', default_factory=<type 'str'>)

An in-memory configuration store that inherits defaultdict behavior. This store is a singleton so only one object is created. Please see bastio.mixin.UniqueSingletonMeta.

The in-memory store takes precedence over the configuration file. If key was not found in the memory store we’ll try to get it from the configuration file, if all fails we will simply return the default value of the default_factory assigned in the constructor.

__getattr__(attr)

There’s only one case where precedence is reversed in favor of the configuration file; when one of the [method]s below are present right before the <option name>. This and once the value is retrieved successfully it will be set in the memory store so that you can access it later without having to consult the configuration file again.

Parameters:attr (str) –

The syntax is [method]_[section]_<option name> where [method] and [section] are optional, and <option name> is required. Note that if you wish not to supply [method] you need to remove [section] and _ as well. Also if [section] was not supplied the default section name that was supplied to the constructor will be used.

[method] could be one of a few possibilities. Either get, getint, getfloat, or getboolean that correspond to the methods available through the ConfigParser interface.

e.g., get_alpha_name will try to get the option name from the configuration file, similarly in the case of get_name we will try to get the option’s value from the configuration file but from under the section that was supplied to the constructor.

Returns:The option’s value or default_factory if no value was set. Raises :bastio.excepts.BastioConfigError

__init__(section='agent', default_factory=<type 'str'>)

Parameters:

• section (str) – The section of the configuration file to use by default.
• default_factory (object) – See collections.defaultdict

__metaclass__

alias of UniqueSingletonMeta

__setattr__(attr, value)

Set a value to the in-memory store.

Parameters:

• attr (str) – The key in the key-value in-memory store.
• value (object) – The value in the key-value in-memory store.

__weakref__

list of weak references to the object (if defined)

load(filename)

Load a configuration file using ConfigParser into memory.

Parameters:filename (str) – The absolute path of the configuration file. Raises :bastio.excepts.BastioConfigError

Concurrency Utilities

module:bastio.concurrency synopsis:Concurrency utilities. author:Amr Ali <amr@databracket.com>

class bastio.concurrency.Failure

A class to wrap an exception info to pass to the failure callback registered on a task to handle it.

This class must only be instantiated from under an except clause.

class bastio.concurrency.Task(target, success=<function <lambda> at 0x2b59c80>, failure=<function <lambda> at 0x2b59cf8>, infinite=False, *args, **kwargs)

A class to describe a task to be used by the thread pool.

An infinite or a blocking task will have to take a kill threading.Event as the first argument to the function to be able to end operations gracefully in case a stop event was triggered.

This class takes two callbacks as keyword arguments to handle the cases where a task succeeds or fails, called success and failure respectively.

Calling the Task.stop() method will signal the worker in the thread pool to stop execution and exit gracefully.

stop()

Signal this task to stop as soon as possible.

class bastio.concurrency.ThreadPool(min_workers=2)

An adaptive thread pool.

This thread pool adapts to the threads consumption rate by making sure that the available number of workers to process tasks is always above the minimum number of workers that should be always available.

add_worker(num=1)

Add worker(s) to the thread pool.

Parameters:num (int) – The number of workers to add to the pool.

remove_all_workers(wait=None)

Remove all workers from the pool.

Remove all active workers from the pool and wait wait seconds until last worker ends, or wait forever if wait is None. This action will also signal all running tasks to stop as soon as possible.

Parameters:wait (float) – Number of seconds to wait or None to wait forever.

remove_worker(num=1)

Remove worker(s) from the thread pool.

Parameters:num (int) – The number of workers to remove from the pool.

run(task)

Start a task.

Parameters:task (Task) – A task to be executed by a worker. Returns:The task that was passed to this method.

class bastio.concurrency.GlobalThreadPool(min_workers=2)

A singleton of bastio.concurrency.ThreadPool.

add_worker(num=1)

Add worker(s) to the thread pool.

Parameters:num (int) – The number of workers to add to the pool.

remove_all_workers(wait=None)

Remove all workers from the pool.

Remove all active workers from the pool and wait wait seconds until last worker ends, or wait forever if wait is None. This action will also signal all running tasks to stop as soon as possible.

Parameters:wait (float) – Number of seconds to wait or None to wait forever.

remove_worker(num=1)

Remove worker(s) from the thread pool.

Parameters:num (int) – The number of workers to remove from the pool.

run(task)

Start a task.

Parameters:task (Task) – A task to be executed by a worker. Returns:The task that was passed to this method.

Logging Facility

module:bastio.log synopsis:Logging facilities for this project. author:Amr Ali <amr@databracket.com>

class bastio.log.Logger(prog='bastio-agent')

A class that provides logging facilities exposed by the underlying Python’s logging module.

enable_stream()

Enable logging to STDOUT. This method is idempotent.

enable_syslog()

Enable Syslog logging. This method is idempotent.

Mixins And Language Helpers

module:bastio.mixin synopsis:Mixins utilities used across the project. author:Amr Ali <amr@databracket.com>

Metaclasses

class bastio.mixin.SingletonAbstractMeta(name, bases, attrs)

A Singleton pattern abstract metaclass.

class bastio.mixin.KindSingletonMeta(name, bases, attrs)

A singleton pattern metaclass that uses the underlying class’ name as the unique constraint.

class bastio.mixin.UniqueSingletonMeta(name, bases, attrs)

A Singleton pattern metaclass that uses arguments passed to the underlying class constructor as the unique constraint.

Data Structure Mixins

class bastio.mixin.Json

A mixin to give objects the ability to serialize and deserialize to/from JSON formatted string.

from_json(json_string)

Deserialize a JSON formatted string and populate the current object with members of the name and value provided in the JSON string.

Returns:self

to_json()

Serialize current object’s members to a JSON formatted string.

This function will only serialize members that don’t start with _ or a callable.

Returns:A JSON formatted string.

Version Information

module:bastio.version synopsis:A module that contain version details for the package. author:Amr Ali <amr@databracket.com>

Update version information here only. There’s no need to update any other file in the package.

Release of a hotfix/bugfix: - Increment version’s BUILD field.

Release of an update that modifies the API but maintains backward compatibility: - Increment version’s MINOR field and reset the BUILD field.

Release of an update that that modifies the API and breaks backward compatibility: - Increment version’s MAJOR field and reset both the MINOR and BUILD fields.

Exceptions

module:bastio.excepts synopsis:Exception classes used by this project. author:Amr Ali <amr@databracket.com>

bastio.excepts.reraise(ex, message=None)

Reraise the exception last happened with the original traceback.

Parameters:

• ex (A subclass of Exception.) – The exception to be raised instead of the original one.
• message (str) – An optional message to replace the old exception’s message.

Raises :

ex

exception bastio.excepts.BastioException

A Bastio general exception

exception bastio.excepts.BastioConfigError

A configuration operation error

exception bastio.excepts.BastioUnimplementedError

An unimplemented operation error

exception bastio.excepts.BastioTaskError

A task operation error

exception bastio.excepts.BastioCryptoError

A cryptographic operation error

exception bastio.excepts.BastioNetstringError

A Netstring parsing or composition error

exception bastio.excepts.BastioEOFError

EOF error

exception bastio.excepts.BastioMessageError

Message parser operation error

exception bastio.excepts.BastioBackendError

A backend client operation error

exception bastio.excepts.BastioAccountError

An account operation error