sshmitm.authentication module

class sshmitm.authentication.Authenticator(session)

Bases: BaseModule

Options for remote authentication.

Parameters:

session (Session)

REQUEST_AGENT_BREAKIN = False

This flag indicates if SSH-MITM should do a breakin to the client’s ssh agent, even in cases where the agent is not forwarded.

abstract 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

abstract auth_password(username, host, port, password)

Performs authentication using a password.

Parameters:
  • username (str)

  • host (str)

  • port (int)

  • password (str)

Return type:

int

abstract 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 (Optional[str], default: None) – remote host username.

  • password (Optional[str], default: None) – remote host password.

  • key (Optional[PKey], 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, *, run_post_auth=True)

Connects to the SSH server and performs the necessary authentication.

Parameters:
  • user (str)

  • host (str)

  • port (int)

  • method (AuthenticationMethod)

  • password (Optional[str], default: None)

  • key (Optional[PKey], default: None)

  • run_post_auth (bool, default: True)

Return type:

int

abstract 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 (Optional[str], default: None) – username which is used during authentication

Return type:

Optional[List[str]]

Returns:

a list of strings representing the available authentication methods.

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

Get the credentials for remote host.

Parameters:
  • username (str) – remote host username.

  • password (Optional[str], default: None) – remote host password.

  • key (Optional[PKey], 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_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 (Optional[str], default: None) – username which is used for authentication

Return type:

Optional[List[str]]

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

exception sshmitm.authentication.PublicKeyEnumerationError

Bases: Exception

class sshmitm.authentication.PublicKeyEnumerator(hostname_or_ip, port)

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)

  • port (int)

check_publickey(username, public_key)
Parameters:
  • username (str)

  • public_key (Union[str, PublicBlob])

Return type:

bool

close()
Return type:

None

connect()
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 (Optional[str], default: None)

  • key (Optional[PKey], default: None)

  • host (Optional[str], default: None)

  • port (Optional[int], default: None)

host: Optional[str]

(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: Optional[PKey]

(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.

password: Optional[str]

(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: Optional[int]

(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.

sshmitm.authentication.patched_parse_service_accept(self, msg)
Parameters:
  • self (AuthHandler)

  • msg (Message)

Return type:

None

sshmitm.authentication.patched_parse_userauth_info_request(self, msg)
Parameters:
  • self (AuthHandler)

  • msg (Message)

Return type:

None