powermolelib package

Submodules

powermolelib.bootstrapagent module

Main code for bootstrapping agent.

NOTE: The BootstrapAgent class is responsible to purge the stream (ie. index in stream is at COMMAND_PROMPT)

class powermolelib.bootstrapagent.BootstrapAgent(tunnel, group_ports, deploy_path='/tmp')

Bases: powermolelib.logging.LoggerMixin

Responsible for executing the python agent module.

is_agent_module_available()

Determines if agent.py module is on target destination host.

remove()

Removes the python Agent module (not implemented, yet).

start()

Executes the agent python module (after checking for availability and running process).

powermolelib.instructor module

Main code for instructor.

class powermolelib.instructor.ForInstructor(group_ports)

Bases: powermolelib.instructor.Instructor

Provides interaction with the Agent, which resides on target destination host, to accommodate FOR mode.

Functions: - forwards connections (FOR) implicitly, because SSH is responsible for forwarding connections, not the Agent - interaction with the heartbeat responder - provide access to OS services (COMMAND) - transfer files (TRANSFER)

start()

Starts the heartbeat responder.

stop()

Terminates the Agent on destination host and started services (heartbeat responder, command server, etc).

class powermolelib.instructor.Instructor(group_ports)

Bases: abc.ABC, powermolelib.logging.LoggerMixin

Models an Instructor to interact with the Agent residing on target destination host.

Note: As the Agent sits on top of target destination hosts’ OS, many functions can be performed more effectively.

send_command(command)

Executes Linux command and returns the response in a byte list.

send_file(src_file_path, dest_path)

Opens the socket and connects to transfer server (ie. Agent) and sends a file.

start()

Starts the necessary programs on target destination host.

stop()

Terminates the started program(s) and the Agent on target destination host.

stop_agent()

Starts the Agent on destination host.

class powermolelib.instructor.PlainInstructor(group_ports)

Bases: powermolelib.instructor.Instructor

Provides interaction with the Agent, which resides on target destination host, to accommodate FOR mode.

Functions: - interaction with the heartbeat responder - provide access to OS services (COMMAND) - transfer files (TRANSFER)

start()

Starts the heartbeat responder.

stop()

Terminates the Agent on destination host and started services (heartbeat responder, command server, etc).

class powermolelib.instructor.TorInstructor(group_ports, outbound_address, inbound_address='localhost')

Bases: powermolelib.instructor.Instructor

Provides interaction with the Agent, which resides on target destination host, to accommodate Tor mode.

Functions: - proxify internet traffic (TOR) - interaction with the heartbeat responder - provide access to OS services (COMMAND) - transfer files (TRANSFER)

start()

Starts the SOCKS proxy and heartbeat responder.

stop()

Terminates the Agent on destination host and all started services (heartbeat responder, proxy server, ..).

powermolelib.instructor.validate_transfer_server_response(response)

Validates the data structure of the content of an incoming HTTP request.

These requests are received by the CommandServer and contains Linux commands.

powermolelib.logging module

Main code for logging.

class powermolelib.logging.LoggerMixin

Bases: object

Contains a logger method for use by other classes.

powermolelib.miscellaneous module

Main code for miscellaneous.

class powermolelib.miscellaneous.Configuration(config_file)

Bases: powermolelib.logging.LoggerMixin

Parses the configuration file and composes the local forwarding string (SSH -L).

get_config(filename)

Validates the data structure and parses the parameters in a dictionary.

class powermolelib.miscellaneous.Heartbeat(local_heartbeat_port, heartbeat_interval=10)

Bases: powermolelib.logging.LoggerMixin

Determines periodically the state of the tunnel.

An KeyboardInterrupt, which is an exception, will propagate through this class and exits this class.

Note: Research if threading with Event.wait or multiprocessing is a better approach.

start_ping()

Sends a HTTP GET request and processes the response.

class powermolelib.miscellaneous.StateManager

Bases: powermolelib.logging.LoggerMixin

Cleans up objects (eg. Tunnel, Assistant) when exiting.

An KeyboardInterrupt, which is an exception, will be caught by this class, or specifically, by __exit__(). Consequently, this method will invoke the _clean_up() to stop all instantiated objects.

add_object(object_)

Collects instantiated Tunnel and Assistant, and shape(s) for clean up purposes.

powermolelib.miscellaneous.start_application(binary_name, binary_location)

Starts the application.

powermolelib.miscellaneous.write_ssh_config_file(path_ssh_cfg_minitor, gateways, destination)

Writes the configuration file with ProxyJump directives for ssh.

The IdentityFile cannot be given as a run-time parameter. Therefore, we resort to a directive in a config file

Returns:True on success, False otherwise. Return type:bool

powermolelib.powermolelibexceptions module

Custom exception code for minitorcorelib.

exception powermolelib.powermolelibexceptions.InvalidConfigurationFile

Bases: Exception

The configuration file provided is not valid.

exception powermolelib.powermolelibexceptions.InvalidDataStructure

Bases: Exception

The data structure is invalid.

exception powermolelib.powermolelibexceptions.TransferError

Bases: Exception

Something went wrong during transfer of the file.

powermolelib.transferagent module

Main code for transferagent.

NOTE: The TransferAgent class is responsible to purge the stream (ie. index in stream is at COMMAND_PROMPT)

class powermolelib.transferagent.TransferAgent(path_ssh_cfg, all_host_addr, deploy_path='/tmp')

Bases: powermolelib.logging.LoggerMixin

Establishes a connection to the target destination host via one or more intermediaries.

start()

Transfers the Agent module.

It determines along the way if the authentication process is successful.

powermolelib.tunnel module

Main code for tunnel.

NOTE: The Tunnel classes are responsible to purge the stream (ie. index in stream is at COMMAND_PROMPT)

class powermolelib.tunnel.Tunnel(path_ssh_cfg, mode, all_host_addr, group_ports, forward_connections=None)

Bases: powermolelib.logging.LoggerMixin

Establishes a connection to the target destination host via one or more intermediaries.

Be aware, the child’s buffer needs to be purged periodically. This can be done by invoking periodically_purge_buffer(). As verbose mode is enabled for SSH (the child process), it will slowly fill up the buffer, so this has to be taken care of. But don’t invoke this method before having start()’ed BootstrapAgent.

debug()

Captures the output of the child (warning: BLOCKING).

periodically_purge_buffer()

Purges the child’s (SSH) output buffer due to buffer limitations.

start(debug=None)

Establishes an SSH tunnel.

It determines along the way if the authentication process is successful.

In addition, this method and mines for ‘Authenticated’ keywords, so we can keep track which hosts have been connected through.

SSH is here a ‘child application’.

Parameters:debug (basestring) – if True, TIMEOUT will not be raised and may block indefinitely. Use only for debugging purposes to capture the output of the child, which is essentially, hidden ‘under the hood’, and write it to a file.

stop()

Closes the SSH connection essentially by terminating the program SSH.

Module contents

Import all parts from all modules here.