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)

__init__(session)

Initializes Authenticator instance.

This class pass the authentication from the client to the server.

Parameters:

session (Session) – an object of sshmitm.session.Session class to store session information.

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

Forwards the client’s credentials to the real SSH server transparently.

This is the default authenticator. It intercepts the credentials offered by the SSH client and replays them against the remote host, supporting all common authentication methods:

  • Password — the password is captured and forwarded as-is.

  • Public key with agent forwarding — the agent is proxied so the remote server can challenge the client’s key directly.

  • Public key without agent — the tool probes the remote server to determine whether the presented key is accepted, then signals success to the client so it will continue and eventually forward its agent.

  • Keyboard-interactive — challenge/response rounds are bridged between client and server in real time.

Usage example

passthrough is the default, so no explicit flag is required. To set it explicitly:

ssh-mitm server --authenticator passthrough

To redirect unauthenticatable sessions to a honeypot instead of dropping them:

ssh-mitm server --enable-auth-fallback \
    --fallback-host 192.0.2.1 \
    --fallback-username honeypot \
    --fallback-password secret

Notes

  • Captured passwords are logged unless --hide-credentials is set.

  • Agent keys are written to <log-dir>/<session-id>/publickeys when a log directory is configured.

  • The honeypot fallback only triggers when the intercepted client cannot be authenticated against the real server (e.g. no agent forwarded, key not accepted).

Parameters:

session (Session)

__init__(session)

Initializes per-session public-key enumeration state.

Parameters:

session (Session) – the active SSH session being intercepted.

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

Authenticates clients against the remote server using their own public key.

Unlike the passthrough authenticator, this variant accepts only public-key authentication where the client holds and can sign with its private key directly. Password, agent forwarding, and keyboard-interactive are rejected.

This authenticator is useful when you want to restrict interception to clients that authenticate with a locally held private key, without relying on agent forwarding.

Usage example

ssh-mitm server --authenticator remoteauth

Notes

  • Clients that use password or keyboard-interactive authentication will be rejected immediately.

  • Agent forwarding is not used — the client must hold the private key locally.

  • The client’s public key is verified against the remote server before the session is established.

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.

__init__()
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)

__init__(hostname_or_ip='', port=0, *, existing_transport=None)
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)

__init__(*, username, password=None, key=None, host=None, port=None)

The __init__ method is the constructor of the class and it is used to initialize the attributes of the class.

Parameters:

  • username (str) – (str) a string representing the username of the remote host. This is a required argument and must be specified when creating an instance of the class.

  • password (str | None, default: 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.

  • key (PKey | None, default: 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.

  • host (str | None, default: 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.

  • port (int | None, default: 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.

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