client

This is a module that offers a modified version of the paramiko-jump-sourced SSHJumpClient class.

That itself is a subclass of paramiko.SSHClient that adds the ability to use a jump host to connect to a target host.

For documentation on its behavior, see the paramiko client documentation.

paramiko-jump is used under the terms of the Apache License 2.0.

Copyright (c) 2020, Andrew Schenck.

Objects provided by this module:

class fabricplus.paramiko_modifications.client.DummyAuthHandler(*items)
Stateful auth handler for paramiko that will return a list of

auth parameters for every CLI prompt

Example

>>> from paramiko_jump import DummyAuthHandler
>>> handler = DummyAuthHandler(['password'], ['1'])
>>> handler()
['password']
>>> handler()
['1']
__call__(*args, **kwargs)

Call self as a function.

__init__(*items)
__weakref__

list of weak references to the object (if defined)

class fabricplus.paramiko_modifications.client.SSHJumpClient(*, jump_session: SSHClient | None = None, auth_handler: Callable | None = None)

Manage an SSH session which is optionally being proxied through a Jump Host.

__init__(*, jump_session: SSHClient | None = None, auth_handler: Callable | None = None) → None

SSHJumpClient constructor, which is a subclass of paramiko.client.SSHClient.

Parameters:

  • jump_session – If provided, proxy SSH connections through the another instance of SSHClient.

  • auth_handler – If provided, keyboard-interactive authentication will be implemented, using this handler as the callback. If this is set to None, use Paramiko’s default authentication algorithm instead of forcing keyboard-interactive authentication.

__repr__() → str

Return repr(self).

Returns:

The class name and the jump session and auth handler.

Return type:

str

__str__() → str

String representation of the object.

Returns:

The class name.

Return type:

str

connect(hostname: str, port: int = 22, username: str | None = None, password: str | None = None, pkey: PKey | None = None, key_filename: str | None = None, timeout: int | None = None, allow_agent: bool = True, look_for_keys: bool = True, compress: bool = False, sock: socket | None = None, gss_auth: bool = False, gss_kex: bool = False, gss_deleg_creds: bool = True, gss_host: str | None = None, banner_timeout: int | None = None, auth_timeout: int | None = None, gss_trust_dns: bool = True, passphrase: str | None = None, disabled_algorithms: Dict[str, List[str]] | None = None) → None

Connect to an SSH server and authenticate to it.

Parameters:

  • hostname – Hostname or IP address of the remote host.

  • port – Port number of the remote host, defaults to SSH_PORT (22)

  • username – Username to authenticate as, defaults to None

  • password – Password to authenticate with, defaults to None

  • pkey – PKey object for private key, defaults to None

  • key_filename – Filename of the private key file, defaults to None

  • timeout – Timeout for the TCP connect, defaults to None

  • allow_agent – Set to False to disable connecting to the SSH agent, defaults to True

  • look_for_keys – Set to False to disable searching for discoverable private key files, defaults to True

  • compress – Set to True to turn on compression, defaults to False

  • sock – Existing socket to use for connection, defaults to None

  • gss_auth – Set to True to allow GSS-API authentication, defaults to False

  • gss_kex – Set to True to allow GSS-API key exchange, defaults to False

  • gss_deleg_creds – Set to True to delegate GSS-API credentials from client to server, defaults to True

  • gss_host – Hostname to use in GSS-API authentication, defaults to None

  • banner_timeout – Timeout for the banner message, defaults to None

  • auth_timeout – Timeout for authentication, defaults to None

  • gss_trust_dns – Set to False to disable DNS lookups for GSS-API, defaults to True

  • passphrase – Passphrase to use for private key, defaults to None

  • disabled_algorithms – A dictionary of disabled algorithms, defaults to None

Raises:

ValueError – If jump_session and sock are both provided as arguments; they are mutually exclusive

Returns:

None

Return type:

None

fabricplus.paramiko_modifications.client.jump_host(hostname: AnyStr, username: AnyStr, password: AnyStr, auth_handler: Callable[[...], Any] | None = None, look_for_keys: bool = True, auto_add_missing_key_policy: bool = False) → Iterator

Example

>>> from paramiko_jump import SSHJumpClient, simple_auth_handler
>>> with jump_host(
>>>         hostname='jump-host',
>>>         username='username') as jump:
>>>     target = SSHJumpClient(jump_session=jumper)
>>>     target.connect(hostname='target-host', username='target-user')
>>>     _, stdout, _ = target.exec_command('sh ver')
>>>     print(stdout.read().decode())
>>>     target.close()
param hostname:

The hostname of the jump host.

param username:

The username used to authenticate with the jump host.

param password:

Password used to authenticate with the jump host.

param auth_handler:

If provided, keyboard-interactive authentication will be implemented, using this handler as the callback. If this is set to None, use Paramiko’s default authentication algorithm instead of forcing keyboard-interactive authentication.

param look_for_keys:

Gives Paramiko permission to look around in our ~/.ssh folder to discover SSH keys on its own (Default False)

param auto_add_missing_key_policy:

If set to True, setting the missing host key policy on the jump is set to auto add policy. (Default False)

return:

Connected SSHJumpClient instance context.

rtype:

Iterator

fabricplus.paramiko_modifications.client.simple_auth_handler(title: AnyStr, instructions: AnyStr, prompt_list: Sequence[Tuple[AnyStr, bool]]) → List

Authentication callback, for keyboard-interactive authentication.

Parameters:

  • title – Displayed to the end user before anything else.

  • instructions – Displayed to the end user. Typically contains text explaining the authentication scheme and / or legal disclaimers.

  • prompt_list – A Sequence of (AnyStr, bool). Each string element is displayed as an end-user input prompt. The corresponding boolean element indicates whether the user input should be ‘echoed’ back to the terminal during the interaction.

Returns:

A list of user input, in the order that the prompts were presented.

Return type:

List[AnyStr]