sshmitm.authentication module

class sshmitm.authentication.Authenticator(session)

Bases: SSHMITMBaseModule

Specifies the authenticator module used for validating user credentials and managing authentication workflows.

Parameters:

session (Session)

abstractmethod auth_agent(username, host, port)

Performs authentication using the ssh-agent.

Parameters:

  • username (str)

  • host (str)

  • port (int)

Return type:

int

auth_fallback(username)

This method is executed when the intercepted client would be allowed to log in to the server, but due to the interception, the login is not possible.

The method checks if a fallback host (a honeypot) has been provided and if not, it closes the session, and logs that authentication is not possible. If the fallback host has been provided, it attempts to log in to the honeypot using the username and password provided, and reports success or failure accordingly. If authentication against the honeypot fails, it logs an error message.

Parameters:

username (str)

Return type:

int

auth_keyboard_interactive(username, host, port, bridge, submethods='')

Perform keyboard-interactive auth with the remote server, proxying challenges via bridge.

Parameters:
Return type:

int

auth_none_remote(username, host, port)

Perform none auth with the remote server.

Parameters:

  • username (str)

  • host (str)

  • port (int)

Return type:

int

abstractmethod auth_password(username, host, port, password)

Performs authentication using a password.

Parameters:

  • username (str)

  • host (str)

  • port (int)

  • password (str)

Return type:

int

abstractmethod auth_publickey(username, host, port, key)

Performs authentication using public key authentication.

Parameters:

  • username (str)

  • host (str)

  • port (int)

  • key (PKey)

Return type:

int

authenticate(username=None, password=None, key=None, store_credentials=True)

Authenticate with the remote host using provided credentials.

Parameters:

  • username (str | None, default: None) – remote host username.

  • password (str | None, default: None) – remote host password.

  • key (PKey | None, default: None) – remote host private key.

  • store_credentials (bool, default: True) – boolean flag to indicate if provided credentials should be stored.

Return type:

int

Returns:

integer representing authentication success or failure.

connect(user, host, port, method, password=None, key=None, interactive_handler=None, interactive_submethods='', *, run_post_auth=True)

Connects to the SSH server and performs the necessary authentication.

Parameters:

  • user (str)

  • host (str)

  • port (int)

  • method (AuthenticationMethod)

  • password (str | None, default: None)

  • key (PKey | None, default: None)

  • interactive_handler (Callable[..., Any] | None, default: None)

  • interactive_submethods (str, default: '')

  • run_post_auth (bool, default: True)

Return type:

int

abstractmethod get_auth_methods(host, port, username=None)

Get the available authentication methods for a remote host.

Parameters:

  • host (str) – remote host address.

  • port (int) – remote host port.

  • username (str | None, default: None) – username which is used during authentication

Return type:

list[str] | None

Returns:

a list of strings representing the available authentication methods.

get_preconnect_address()
Return type:

tuple[str, int] | None

get_remote_host_credentials(username, password=None, key=None)

Get the credentials for remote host.

Parameters:

  • username (str) – remote host username.

  • password (str | None, default: None) – remote host password.

  • key (PKey | None, default: None) – remote host private key.

Return type:

RemoteCredentials

Returns:

an object of RemoteCredentials class.

on_session_close()

Performs actions when the session is closed.

Return type:

None

classmethod parser_arguments()

Adds the options for remote authentication using argparse.

Return type:

None

post_auth_action(success)

Perform any post-authentication actions.

This method is called after the authentication process is completed, whether successfully or not.

Parameters:

success (bool) – indicates if the authentication was successful or not

Return type:

None

pre_auth_action()

Perform any pre-authentication actions.

This method is called before the authentication process starts.

Return type:

None

class sshmitm.authentication.AuthenticatorPassThrough(session)

Bases: Authenticator

A subclass of Authenticator which passes the authentication to the remote server.

This class reuses the credentials received from the client and sends it directly to the remote server for authentication.

Parameters:

session (Session)

auth_agent(username, host, port)

Performs authentication using the ssh-agent.

Parameters:

  • username (str)

  • host (str)

  • port (int)

Return type:

int

auth_keyboard_interactive(username, host, port, bridge, submethods='')

Perform keyboard-interactive auth with the remote server, proxying challenges via bridge.

Parameters:
Return type:

int

auth_none_remote(username, host, port)

Perform none auth with the remote server.

Parameters:

  • username (str)

  • host (str)

  • port (int)

Return type:

int

auth_password(username, host, port, password)

Performs authentication using a password.

Parameters:

  • username (str)

  • host (str)

  • port (int)

  • password (str)

Return type:

int

auth_publickey(username, host, port, key)

Performs authentication using public key authentication.

This method is checking if a user with a specific public key is allowed to log into a server using the SSH protocol. If the key can sign, the method will try to connect to the server using the public key. If the connection is successful, the user is considered authenticated.

If the key cannot sign, the method will check if the key is valid for the host and port specified for the user. If the key is valid, the user is considered authenticated.

If the key is not valid, or if there is any error while checking if the key is valid, the user will not be authenticated and will not be able to log in.

Parameters:

  • username (str)

  • host (str)

  • port (int)

  • key (PKey)

Return type:

int

get_auth_methods(host, port, username=None)

Get the available authentication methods for a remote host.

Parameters:

  • host (str) – remote host address.

  • port (int) – remote host port.

  • username (str | None, default: None) – username which is used for authentication

Return type:

list[str] | None

Returns:

a list of strings representing the available authentication methods.

on_session_close()

Performs actions when the session is closed.

Return type:

None

classmethod parser_arguments()

Adds the options for remote authentication using argparse.

Return type:

None

post_auth_action(success)

This method logs information about an authentication event.

The success parameter determines whether the authentication was successful or not. If the authentication was successful, the log will show a message saying “Remote authentication succeeded”.

If not, the log will show “Remote authentication failed”. The log will also show the remote address, username, and password used for authentication (if provided). Information about the accepted public key and remote public key (if any) will also be included in the log. If there is an agent available, the number of keys it has will be displayed, along with details about each key (name, hash, number of bits, and whether it can sign).

All this information can be saved to a log file for later review.

Parameters:

success (bool)

Return type:

None

class sshmitm.authentication.AuthenticatorRemote(session)

Bases: Authenticator

Parameters:

session (Session)

auth_agent(_username, _host, _port)

Performs authentication using the ssh-agent.

Parameters:

  • _username (str)

  • _host (str)

  • _port (int)

Return type:

int

auth_password(_username, _host, _port, _password)

Performs authentication using a password.

Parameters:

  • _username (str)

  • _host (str)

  • _port (int)

  • _password (str)

Return type:

int

auth_publickey(username, host, port, key)

Performs authentication using public key authentication.

Parameters:

  • username (str)

  • host (str)

  • port (int)

  • key (PKey)

Return type:

int

get_auth_methods(_host, _port, _username=None)

Get the available authentication methods for a remote host.

Parameters:

  • host – remote host address.

  • port – remote host port.

  • username – username which is used during authentication

  • _host (str)

  • _port (int)

  • _username (str | None, default: None)

Return type:

list[str] | None

Returns:

a list of strings representing the available authentication methods.

classmethod parser_arguments()

Adds the options for remote authentication using argparse.

Return type:

None

class sshmitm.authentication.KeyboardInteractiveBridge

Bases: object

Thread-safe queue-based bridge for RFC 4256 keyboard-interactive passthrough.

The remote auth thread calls remote_handler() each challenge round (blocking until the client responds). The MITM server-side calls get_next_challenge() to receive prompts and send_responses() to unblock the handler. set_auth_result() is called once when the remote auth exchange completes.

get_next_challenge(timeout=30.0)

Wait for the next event: (“challenge”, title, instructions, prompts) or (“result”, int).

Parameters:

timeout (float, default: 30.0)

Return type:

tuple[Any, ...] | None

remote_handler(title, instructions, prompt_list)

Called by paramiko in the remote auth thread for each challenge round.

Parameters:

  • title (str)

  • instructions (str)

  • prompt_list (list[tuple[str, bool]])

Return type:

list[str]

send_responses(responses)

Provide client responses to unblock the remote_handler.

Parameters:

responses (list[str])

Return type:

None

set_auth_result(success)

Signal auth completion to the MITM server-side.

Parameters:

success (bool)

Return type:

None

exception sshmitm.authentication.PublicKeyEnumerationError

Bases: Exception

class sshmitm.authentication.PublicKeyEnumerator(hostname_or_ip='', port=0, *, existing_transport=None)

Bases: object

Probe a remote host to determine if the provided public key is authorized for the provided username.

The PublicKeyEnumerator takes four arguments: hostname_or_ip (a string representing hostname or IP address), port (an integer representing the port number), username (a string representing the username), and public_key (a public key in paramiko.pkey.PublicBlob format). The function returns a boolean indicating if the provided public key is authorized or not.

The PublicKeyEnumerator uses the paramiko library to perform the probe by creating a secure shell (SSH) connection to the remote host and performing authentication using the provided username and public key. Two helper functions, valid and parse_service_accept, are defined inside the check_publickey function to assist with the authentication process.

The PublicKeyEnumerator function opens a socket connection to the remote host and starts an SSH transport using the paramiko library. The function then generates a random private key, replaces the public key with the provided key, and performs the public key using transport.auth_publickey. The result of the authentication is stored in the valid_key variable. If the authentication fails, an exception of type paramiko.ssh_exception.AuthenticationException is raised and caught, leaving the valid_key variable as False. Finally, the function returns the value of valid_key, which indicates whether the provided public key is authorized or not.

Parameters:

  • hostname_or_ip (str, default: '')

  • port (int, default: 0)

  • existing_transport (Transport | None, default: None)

check_publickey(username, public_key)
Parameters:

  • username (str)

  • public_key (str | PublicBlob)

Return type:

bool

close()
Return type:

None

connect()
Return type:

None

mark_service_ready()

Signal that the ssh-userauth service is already active (e.g. after a prior auth_none call).

Return type:

None

class sshmitm.authentication.RemoteCredentials(*, username, password=None, key=None, host=None, port=None)

Bases: object

The RemoteCredentials class represents the credentials required to access a remote host.

Parameters:

  • username (str)

  • password (str | None, default: None)

  • key (PKey | None, default: None)

  • host (str | None, default: None)

  • port (int | None, default: None)

host: str | None

(str) an optional string representing the hostname or IP address of the remote host. This argument is optional and if not specified, the value will be None.

key: PKey | None

(PKey) an optional PKey object representing a private key used to authenticate with the remote host. This argument is optional and if not specified, the value will be None.

static load_private_key(path, passphrase=None)

Loads an OpenSSH private key from a file and returns a Paramiko PKey object.

Parameters:

  • path (str) – Path to the private key file (e.g., ~/.ssh/id_ed25519)

  • passphrase (str | None, default: None) – Optional password for encrypted keys

Return type:

PKey

Returns:

Instance of paramiko.PKey (e.g., RSAKey, Ed25519Key, ECDSAKey)

Raises:

paramiko.ssh_exception.SSHException for invalid or unknown key format

password: str | None

(str) an optional string representing the password of the remote host. This argument is optional and if not specified, the value will be None.

port: int | None

(int) an optional integer representing the port number used to connect to the remote host. This argument is optional and if not specified, the value will be None.

username: str

(str) a string representing the username of the remote host.

On this page
Edit on GitHub