sshmitm.session module

Session Class

The Session class provides the ability to start, manage, and close an interactive session between a client and a server. It provides a convenient and exception-safe way to handle sessions in your application.

try:
    with Session(self, client, addr, self.authenticator, remoteaddr) as session:
        if session.start():
            while session.running:
                # session is running
                pass
        else:
            logging.warning("(%s) session not started", session)
except Exception:
    logging.exception("error handling session creation")

This code creates a session object using the session_class method, and wraps it in a with statement. The start method is then called on the session object. If the start method returns True, the session is considered running and the running property of the session is checked in a while loop. If the start method returns False, a warning message is logged indicating that the session was not started. If any exceptions are raised during session creation, they are logged using the logging.exception method.

class sshmitm.session.AuthState(username='', username_provided=None, password=None, password_provided=None, remote_key=None, accepted_key=None, agent=None, kbdint_responses=<factory>)

Bases: object

Parameters:

  • username (str, default: '')

  • username_provided (str | None, default: None)

  • password (str | None, default: None)

  • password_provided (str | None, default: None)

  • remote_key (PKey | None, default: None)

  • accepted_key (PKey | None, default: None)

  • agent (AgentProxy | None, default: None)

  • kbdint_responses (list[tuple[str, str]], default: <factory>)

__init__(username='', username_provided=None, password=None, password_provided=None, remote_key=None, accepted_key=None, agent=None, kbdint_responses=<factory>)
Parameters:

  • username (str, default: '')

  • username_provided (str | None, default: None)

  • password (str | None, default: None)

  • password_provided (str | None, default: None)

  • remote_key (PKey | None, default: None)

  • accepted_key (PKey | None, default: None)

  • agent (AgentProxy | None, default: None)

  • kbdint_responses (list[tuple[str, str]], default: <factory>)

accepted_key: PKey | None = None
agent: AgentProxy | None = None
kbdint_responses: list[tuple[str, str]]
password: str | None = None
password_provided: str | None = None
remote_key: PKey | None = None
username: str = ''
username_provided: str | None = None
class sshmitm.session.BaseSession

Bases: SSHMITMBaseModule

Sets the custom session class for SSH-MITM, controlling session behavior, logging, and interaction handling.

__init__()
register_session_thread()
Return type:

None

class sshmitm.session.NetconfState(requested=False, command=b'', client=None, client_ready=<factory>, server_capabilities=<factory>, client_capabilities=<factory>, use_chunked=False)

Bases: object

Parameters:

  • requested (bool, default: False)

  • command (bytes, default: b'')

  • client (NetconfClient | None, default: None)

  • client_ready (Event, default: <factory>)

  • server_capabilities (frozenset[str], default: <factory>)

  • client_capabilities (frozenset[str], default: <factory>)

  • use_chunked (bool, default: False)

__init__(requested=False, command=b'', client=None, client_ready=<factory>, server_capabilities=<factory>, client_capabilities=<factory>, use_chunked=False)
Parameters:

  • requested (bool, default: False)

  • command (bytes, default: b'')

  • client (NetconfClient | None, default: None)

  • client_ready (Event, default: <factory>)

  • server_capabilities (frozenset[str], default: <factory>)

  • client_capabilities (frozenset[str], default: <factory>)

  • use_chunked (bool, default: False)

client: NetconfClient | None = None
client_capabilities: frozenset[str]

Capabilities advertised by the client in its <hello>.

client_ready: Event
command: bytes = b''
requested: bool = False
server_capabilities: frozenset[str]

Capabilities advertised by the remote NETCONF server in its <hello>.

use_chunked: bool = False

1.1 (RFC 6242 chunked framing).

Type:

True when both sides negotiated

Type:

base

class sshmitm.session.PowerShellState(requested=False, command=b'', client=None, client_ready=<factory>)

Bases: object

Parameters:

  • requested (bool, default: False)

  • command (bytes, default: b'')

  • client (PowerShellClient | None, default: None)

  • client_ready (Event, default: <factory>)

__init__(requested=False, command=b'', client=None, client_ready=<factory>)
Parameters:

  • requested (bool, default: False)

  • command (bytes, default: b'')

  • client (PowerShellClient | None, default: None)

  • client_ready (Event, default: <factory>)

client: PowerShellClient | None = None
client_ready: Event
command: bytes = b''
requested: bool = False
class sshmitm.session.RemoteState(socket_address, address=<factory>, address_reachable=True)

Bases: object

Parameters:

  • socket_address (tuple[str, int] | tuple[str, int, int, int])

  • address (tuple[str | None, int | None], default: <factory>)

  • address_reachable (bool, default: True)

__init__(socket_address, address=<factory>, address_reachable=True)
Parameters:

  • socket_address (tuple[str, int] | tuple[str, int, int, int])

  • address (tuple[str | None, int | None], default: <factory>)

  • address_reachable (bool, default: True)

address: tuple[str | None, int | None]
address_reachable: bool = True
socket_address: tuple[str, int] | tuple[str, int, int, int]
class sshmitm.session.SCPState(requested=False, command=b'', handler_entry=None)

Bases: object

Parameters:

  • requested (bool, default: False)

  • command (bytes, default: b'')

  • handler_entry (ExecHandlerEntry | None, default: None)

__init__(requested=False, command=b'', handler_entry=None)
Parameters:

  • requested (bool, default: False)

  • command (bytes, default: b'')

  • handler_entry (ExecHandlerEntry | None, default: None)

command: bytes = b''
handler_entry: ExecHandlerEntry | None = None
requested: bool = False
class sshmitm.session.SFTPState(requested=False, channel=None, client=None, client_ready=<factory>)

Bases: object

Parameters:

  • requested (bool, default: False)

  • channel (Channel | None, default: None)

  • client (SFTPClient | None, default: None)

  • client_ready (Event, default: <factory>)

__init__(requested=False, channel=None, client=None, client_ready=<factory>)
Parameters:

  • requested (bool, default: False)

  • channel (Channel | None, default: None)

  • client (SFTPClient | None, default: None)

  • client_ready (Event, default: <factory>)

channel: Channel | None = None
client: SFTPClient | None = None
client_ready: Event
requested: bool = False
class sshmitm.session.SSHState(requested=False, client=None, client_auth_finished=False, client_created=<factory>, pty_kwargs=None, remote_channel=None)

Bases: object

Parameters:

  • requested (bool, default: False)

  • client (SSHClient | None, default: None)

  • client_auth_finished (bool, default: False)

  • client_created (Condition, default: <factory>)

  • pty_kwargs (dict[str, Any] | None, default: None)

  • remote_channel (Channel | None, default: None)

__init__(requested=False, client=None, client_auth_finished=False, client_created=<factory>, pty_kwargs=None, remote_channel=None)
Parameters:

  • requested (bool, default: False)

  • client (SSHClient | None, default: None)

  • client_auth_finished (bool, default: False)

  • client_created (Condition, default: <factory>)

  • pty_kwargs (dict[str, Any] | None, default: None)

  • remote_channel (Channel | None, default: None)

client: SSHClient | None = None
client_auth_finished: bool = False
client_created: Condition
pty_kwargs: dict[str, Any] | None = None
remote_channel: Channel | None = None
requested: bool = False
class sshmitm.session.Session(proxyserver, client_socket, client_address, authenticator, remoteaddr, banner_name=None)

Bases: BaseSession

Manages an intercepted SSH session from handshake to teardown.

This is the default session class. It tracks all state for a single client connection — authentication credentials, transport, active channels, and protocol-specific state for SSH, SCP, SFTP, NETCONF, and PowerShell.

A session log directory can be configured with --session-log-dir; plugins use this path to store captured data under <log-dir>/<session-id>/.

Usage example

ssh-mitm server --session-class base

Notes

  • This is the default session class; no explicit flag is needed unless using a custom session implementation.

  • The maximum number of concurrent connections can be capped with --max-connections (default: 100; 0 = unlimited).

Parameters:

  • proxyserver (SSHProxyServer)

  • client_socket (socket)

  • client_address (tuple[str, int] | tuple[str, int, int, int])

  • authenticator (type[Authenticator])

  • remoteaddr (tuple[str, int] | tuple[str, int, int, int])

  • banner_name (str | None, default: None)

CIPHERS = None
__init__(proxyserver, client_socket, client_address, authenticator, remoteaddr, banner_name=None)
Parameters:

  • proxyserver (SSHProxyServer) – the proxy server instance managing this session.

  • client_socket (socket) – the socket representing the incoming client connection.

  • client_address (tuple[str, int] | tuple[str, int, int, int]) – address information of the connecting client.

  • authenticator (type[Authenticator]) – the authenticator class to use for this session.

  • remoteaddr (tuple[str, int] | tuple[str, int, int, int]) – the remote address to connect to.

  • banner_name (str | None, default: None) – optional custom SSH banner name sent to the client.

agent_requested: Event
authenticator: Authenticator
channel: Channel | None
close()

Close the session and release the underlying resources.

Return type:

None

env_requests: dict[bytes, bytes]
finalize_upstream_transport()
Return type:

None

get_session_log_dir()

Returns the directory where the ssh session logs will be stored.

Return type:

str | None

Returns:

The directory path where the ssh session logs will be stored, or None if the directory is not specified.

property netconf_channel: Channel | None
classmethod parser_arguments()

Add an argument to the command line parser for session plugin.

Return type:

None

property powershell_channel: Channel | None
proxyserver: SSHProxyServer
property running: bool

Returns the running state of the current session.

Returns:

A boolean indicating whether the session is running or not

property scp_channel: Channel | None
session_log_dir: str | None
property ssh_channel: Channel | None
start()

Start the session and initialize the underlying transport.

Return type:

bool

property transport: Transport

Returns the type of transport being used by the current session.

Returns:

A string representing the transport type

On this page
Edit on GitHub