sshmitm.plugins.ssh.mirrorshell module

class sshmitm.plugins.ssh.mirrorshell.InjectServer(server_channel)

Bases: ServerInterface

Parameters:

server_channel (Channel)

check_auth_none(username)

Determine if a client may open channels with no (further) authentication.

Return AUTH_FAILED if the client must authenticate, or AUTH_SUCCESSFUL if it’s okay for the client to not authenticate.

The default implementation always returns AUTH_FAILED.

Parameters:

  • username (str) – the username of the client.

  • username

Returns:

AUTH_FAILED if the authentication fails; AUTH_SUCCESSFUL if it succeeds.

Return type:

int

check_channel_pty_request(channel, term, width, height, pixelwidth, pixelheight, modes)

Determine if a pseudo-terminal of the given dimensions (usually requested for shell access) can be provided on the given channel.

The default implementation always returns False.

Parameters:

  • channel (Channel) – the .Channel the pty request arrived on.

  • term (bytes) – type of terminal requested (for example, "vt100").

  • width (int) – width of screen in characters.

  • height (int) – height of screen in characters.

  • pixelwidth (int) – width of screen in pixels, if known (may be 0 if unknown).

  • pixelheight (int) – height of screen in pixels, if known (may be 0 if unknown).

  • channel

  • term

  • width

  • height

  • pixelwidth

  • pixelheight

  • modes (bytes)

Return type:

bool

Returns:

True if the pseudo-terminal has been allocated; False otherwise.

check_channel_request(kind, chanid)

Determine if a channel request of a given type will be granted, and return OPEN_SUCCEEDED or an error code. This method is called in server mode when the client requests a channel, after authentication is complete.

If you allow channel requests (and an ssh server that didn’t would be useless), you should also override some of the channel request methods below, which are used to determine which services will be allowed on a given channel:

  • check_channel_pty_request

  • check_channel_shell_request

  • check_channel_subsystem_request

  • check_channel_window_change_request

  • check_channel_x11_request

  • check_channel_forward_agent_request

The chanid parameter is a small number that uniquely identifies the channel within a .Transport. A .Channel object is not created unless this method returns OPEN_SUCCEEDED – once a .Channel object is created, you can call .Channel.get_id to retrieve the channel ID.

The return value should either be OPEN_SUCCEEDED (or 0) to allow the channel request, or one of the following error codes to reject it:

  • OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED

  • OPEN_FAILED_CONNECT_FAILED

  • OPEN_FAILED_UNKNOWN_CHANNEL_TYPE

  • OPEN_FAILED_RESOURCE_SHORTAGE

The default implementation always returns OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED.

Parameters:

  • kind (str) – the kind of channel the client would like to open (usually "session").

  • chanid (int) – ID of the channel

  • kind

  • chanid

Return type:

int

Returns:

an int success or failure code (listed above)

check_channel_shell_request(channel)

Determine if a shell will be provided to the client on the given channel. If this method returns True, the channel should be connected to the stdin/stdout of a shell (or something that acts like a shell).

The default implementation always returns False.

Parameters:

  • channel (Channel) – the .Channel the request arrived on.

  • channel

Return type:

bool

Returns:

True if this channel is now hooked up to a shell; False if a shell can’t or won’t be provided.

class sshmitm.plugins.ssh.mirrorshell.SSHMirrorForwarder(session)

Bases: SSHForwarder

Mirror an SSH shell session to a second client (live session monitoring and injection)

This plugin opens a secondary SSH listener on a random port for each intercepted session. A second client (e.g. a security analyst) can connect to that port with a plain ssh command and observe the session in real time. The mirror client can also type into the terminal - keystrokes are forwarded to the remote server as if they came from the original user.

Usage example

Start SSH-MITM with the mirror-shell plugin:

ssh-mitm server --ssh-forwarder sshmitm.plugins.ssh.mirrorshell.SSHMirrorForwarder

When a client connects, SSH-MITM prints a connection hint similar to:

[i] created mirrorshell on port 34521. connect with: ssh -p 34521 127.0.0.1

Connect from a second terminal to observe (and optionally interact with) the session:

ssh -p 34521 127.0.0.1

Notes

  • Only one mirror client can be connected per session at a time. A new connection replaces the previous one.

  • The mirror connection uses no authentication - any client that can reach the listener port can connect. Bind to a restricted interface (--ssh-mirrorshell-net 127.0.0.1) when running in untrusted environments.

  • Session recordings are stored under <log-dir>/<session-id>/terminal_sessions/ and consist of three files per session: ssh_in_*.log, ssh_out_*.log, and ssh_time_*.log. Play back a recording with:

    scriptreplay ssh_time_<ts>.log ssh_out_<ts>.log
Parameters:

session (Session)

HOST_KEY_LENGTH = 2048
close_session(channel)
Parameters:

channel (Channel)

Return type:

None

handle_client_data(data)
Parameters:

data (bytes)

Return type:

bytes

handle_server_data(data)
Parameters:

data (bytes)

Return type:

bytes

handle_server_error(data)
Parameters:

data (bytes)

Return type:

bytes

injector_connect()
Return type:

None

classmethod parser_arguments()

Configures command-line arguments for the SSH-MirrorShell plugin.

Available Arguments:

Return type:

None

--ssh-mirrorshell-net <address>

Specifies the local address or network interface on which the SSH injector listener binds. This determines where the SSH server will accept connections.

  • Default: 0.0.0.0 (all available interfaces)

  • Example: 127.0.0.1 (restricts access to the local machine only)

--ssh-mirrorshell-key <path>

Path to an RSA private key file used as the host key for the SSH injector server. If omitted, a temporary 2048-bit RSA key is generated for each session.

  • Purpose: Using a fixed key avoids “host-key-changed” warnings when

reconnecting to the server. - Example: --ssh-mirrorshell-key /path/to/private_key.pem

--store-ssh-session

Enables recording of the complete terminal session (stdin, stdout, stderr) to disk in scriptreplay format. This is useful for auditing or debugging.

  • Requirement: --log-dir must be set to specify where log files are stored.

  • Note: Logs are saved in a format compatible with the scriptreplay tool.

--ssh-terminal-log-formatter script

Selects the format for terminal session logs. Currently, only script is supported, which produces files compatible with the scriptreplay utility.

  • Default: script