sshmitm.mockserver package

SSH mock server library for testing and development.

class sshmitm.mockserver.IterativeKbdintServer(rounds)

Bases: ServerInterface

Keyboard-interactive server that sends prompts in sequential rounds.

Each KbdintRound is a separate SSH_MSG_USERAUTH_INFO_REQUEST message. The server waits for the client’s response before sending the next round. Every round may carry a different number of prompts (RFC 4256 allows zero or more per round).

Example — two rounds, two prompts each:

server = IterativeKbdintServer(rounds=[
    KbdintRound(
        prompts=[("OTP Token: ", True), ("PIN: ", False)],
        answers=["123456", "9876"],
        name="Step 1",
    ),
    KbdintRound(
        prompts=[("Password: ", False)],
        answers=["secret"],
        name="Step 2",
    ),
])
Parameters:

rounds (list[KbdintRound])

check_auth_interactive(username, submethods)

Begin an interactive authentication challenge, if supported. You should override this method in server mode if you want to support the "keyboard-interactive" auth type, which requires you to send a series of questions for the client to answer.

Return AUTH_FAILED if this auth method isn’t supported. Otherwise, you should return an .InteractiveQuery object containing the prompts and instructions for the user. The response will be sent via a call to check_auth_interactive_response.

The default implementation always returns AUTH_FAILED.

Parameters:

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

  • submethods (str) – a comma-separated list of methods preferred by the client (usually empty)

  • username

  • submethods

Returns:

AUTH_FAILED if this auth method isn’t supported; otherwise an object containing queries for the user

Return type:

int or .InteractiveQuery

check_auth_interactive_response(responses)

Continue or finish an interactive authentication challenge, if supported. You should override this method in server mode if you want to support the "keyboard-interactive" auth type.

Return AUTH_FAILED if the responses are not accepted, AUTH_SUCCESSFUL if the responses are accepted and complete the authentication, or AUTH_PARTIALLY_SUCCESSFUL if your authentication is stateful, and this set of responses is accepted for authentication, but more authentication is required. (In this latter case, get_allowed_auths will be called to report to the client what options it has for continuing the authentication.)

If you wish to continue interactive authentication with more questions, you may return an .InteractiveQuery object, which should cause the client to respond with more answers, calling this method again. This cycle can continue indefinitely.

The default implementation always returns AUTH_FAILED.

Parameters:

responses (list[str]) – list of str responses from the client

Returns:

AUTH_FAILED if the authentication fails; AUTH_SUCCESSFUL if it succeeds; AUTH_PARTIALLY_SUCCESSFUL if the interactive auth is successful, but authentication must continue; otherwise an object containing queries for the user

Return type:

int or .InteractiveQuery

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_auth_password(username, password)

Determine if a given username and password supplied by the client is acceptable for use in authentication.

Return AUTH_FAILED if the password is not accepted, AUTH_SUCCESSFUL if the password is accepted and completes the authentication, or AUTH_PARTIALLY_SUCCESSFUL if your authentication is stateful, and this key is accepted for authentication, but more authentication is required. (In this latter case, get_allowed_auths will be called to report to the client what options it has for continuing the authentication.)

The default implementation always returns AUTH_FAILED.

Parameters:

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

  • password (str) – the password given by the client.

  • username

  • password

Returns:

AUTH_FAILED if the authentication fails; AUTH_SUCCESSFUL if it succeeds; AUTH_PARTIALLY_SUCCESSFUL if the password auth is successful, but authentication must continue.

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.

get_allowed_auths(username)

Return a list of authentication methods supported by the server. This list is sent to clients attempting to authenticate, to inform them of authentication methods that might be successful.

The “list” is actually a string of comma-separated names of types of authentication. Possible values are "password", "publickey", and "none".

The default implementation always returns "password".

Parameters:

  • username (str) – the username requesting authentication.

  • username

Return type:

str

Returns:

a comma-separated str of authentication types

class sshmitm.mockserver.KbdintRound(prompts, answers, name='', instructions='')

Bases: object

One round of a keyboard-interactive exchange.

A single auth attempt may consist of multiple rounds sent one after the other. Each round carries its own set of prompts and expected answers, plus optional name and instructions shown to the user.

Example — OTP followed by a password in separate rounds:

rounds = [
    KbdintRound(prompts=[("OTP Token: ", True)],  answers=["123456"]),
    KbdintRound(prompts=[("Password: ", False)],  answers=["secret"]),
]
Parameters:

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

  • answers (list[str])

  • name (str, default: '')

  • instructions (str, default: '')

answers: list[str]
instructions: str = ''
name: str = ''
prompts: list[tuple[str, bool]]
class sshmitm.mockserver.KeyboardInteractiveServer(prompts, answers, name='', instructions='')

Bases: ServerInterface

Keyboard-interactive server with configurable prompts and expected answers.

Parameters:

  • prompts (list[tuple[str, bool]]) – list of (label, echo) tuples — one entry per prompt shown to the client

  • answers (list[str]) – expected correct answers in the same order as prompts

  • name (str, default: '') – challenge name forwarded to the client

  • instructions (str, default: '') – instructions forwarded to the client

check_auth_interactive(username, submethods)

Begin an interactive authentication challenge, if supported. You should override this method in server mode if you want to support the "keyboard-interactive" auth type, which requires you to send a series of questions for the client to answer.

Return AUTH_FAILED if this auth method isn’t supported. Otherwise, you should return an .InteractiveQuery object containing the prompts and instructions for the user. The response will be sent via a call to check_auth_interactive_response.

The default implementation always returns AUTH_FAILED.

Parameters:

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

  • submethods (str) – a comma-separated list of methods preferred by the client (usually empty)

  • username

  • submethods

Returns:

AUTH_FAILED if this auth method isn’t supported; otherwise an object containing queries for the user

Return type:

int or .InteractiveQuery

check_auth_interactive_response(responses)

Continue or finish an interactive authentication challenge, if supported. You should override this method in server mode if you want to support the "keyboard-interactive" auth type.

Return AUTH_FAILED if the responses are not accepted, AUTH_SUCCESSFUL if the responses are accepted and complete the authentication, or AUTH_PARTIALLY_SUCCESSFUL if your authentication is stateful, and this set of responses is accepted for authentication, but more authentication is required. (In this latter case, get_allowed_auths will be called to report to the client what options it has for continuing the authentication.)

If you wish to continue interactive authentication with more questions, you may return an .InteractiveQuery object, which should cause the client to respond with more answers, calling this method again. This cycle can continue indefinitely.

The default implementation always returns AUTH_FAILED.

Parameters:

responses (list[str]) – list of str responses from the client

Returns:

AUTH_FAILED if the authentication fails; AUTH_SUCCESSFUL if it succeeds; AUTH_PARTIALLY_SUCCESSFUL if the interactive auth is successful, but authentication must continue; otherwise an object containing queries for the user

Return type:

int or .InteractiveQuery

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_auth_password(username, password)

Determine if a given username and password supplied by the client is acceptable for use in authentication.

Return AUTH_FAILED if the password is not accepted, AUTH_SUCCESSFUL if the password is accepted and completes the authentication, or AUTH_PARTIALLY_SUCCESSFUL if your authentication is stateful, and this key is accepted for authentication, but more authentication is required. (In this latter case, get_allowed_auths will be called to report to the client what options it has for continuing the authentication.)

The default implementation always returns AUTH_FAILED.

Parameters:

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

  • password (str) – the password given by the client.

  • username

  • password

Returns:

AUTH_FAILED if the authentication fails; AUTH_SUCCESSFUL if it succeeds; AUTH_PARTIALLY_SUCCESSFUL if the password auth is successful, but authentication must continue.

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.

get_allowed_auths(username)

Return a list of authentication methods supported by the server. This list is sent to clients attempting to authenticate, to inform them of authentication methods that might be successful.

The “list” is actually a string of comma-separated names of types of authentication. Possible values are "password", "publickey", and "none".

The default implementation always returns "password".

Parameters:

  • username (str) – the username requesting authentication.

  • username

Return type:

str

Returns:

a comma-separated str of authentication types

class sshmitm.mockserver.MockAgent(key)

Bases: object

Minimal SSH agent protocol server backed by a single paramiko key.

Starts a Unix-socket listener and handles SSH_AGENTC_REQUEST_IDENTITIES and SSH_AGENTC_SIGN_REQUEST messages so that any SSH client that reads SSH_AUTH_SOCK can authenticate with the key without needing a key file.

Usage:

agent = MockAgent(key)
agent.start("/tmp/mock-agent.sock")
# set SSH_AUTH_SOCK=/tmp/mock-agent.sock in the client environment
agent.stop()
Parameters:

key (PKey)

start(path)

Start listening on path (Unix socket).

Parameters:

path (str)

Return type:

None

stop()

Stop the agent.

Return type:

None

class sshmitm.mockserver.MockServerInterface(username, password, pubkeys, allow_none)

Bases: ServerInterface

Full-featured server supporting all four auth methods.

Used by python -m sshmitm.mockserver for interactive CLI use.

Parameters:

  • username (str)

  • password (str | None)

  • pubkeys (list[PKey])

  • allow_none (bool)

check_auth_interactive(username, submethods)

Begin an interactive authentication challenge, if supported. You should override this method in server mode if you want to support the "keyboard-interactive" auth type, which requires you to send a series of questions for the client to answer.

Return AUTH_FAILED if this auth method isn’t supported. Otherwise, you should return an .InteractiveQuery object containing the prompts and instructions for the user. The response will be sent via a call to check_auth_interactive_response.

The default implementation always returns AUTH_FAILED.

Parameters:

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

  • submethods (bytes | str) – a comma-separated list of methods preferred by the client (usually empty)

  • username

  • submethods

Returns:

AUTH_FAILED if this auth method isn’t supported; otherwise an object containing queries for the user

Return type:

int or .InteractiveQuery

check_auth_interactive_response(responses)

Continue or finish an interactive authentication challenge, if supported. You should override this method in server mode if you want to support the "keyboard-interactive" auth type.

Return AUTH_FAILED if the responses are not accepted, AUTH_SUCCESSFUL if the responses are accepted and complete the authentication, or AUTH_PARTIALLY_SUCCESSFUL if your authentication is stateful, and this set of responses is accepted for authentication, but more authentication is required. (In this latter case, get_allowed_auths will be called to report to the client what options it has for continuing the authentication.)

If you wish to continue interactive authentication with more questions, you may return an .InteractiveQuery object, which should cause the client to respond with more answers, calling this method again. This cycle can continue indefinitely.

The default implementation always returns AUTH_FAILED.

Parameters:

responses (list[str]) – list of str responses from the client

Returns:

AUTH_FAILED if the authentication fails; AUTH_SUCCESSFUL if it succeeds; AUTH_PARTIALLY_SUCCESSFUL if the interactive auth is successful, but authentication must continue; otherwise an object containing queries for the user

Return type:

int or .InteractiveQuery

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_auth_password(username, password)

Determine if a given username and password supplied by the client is acceptable for use in authentication.

Return AUTH_FAILED if the password is not accepted, AUTH_SUCCESSFUL if the password is accepted and completes the authentication, or AUTH_PARTIALLY_SUCCESSFUL if your authentication is stateful, and this key is accepted for authentication, but more authentication is required. (In this latter case, get_allowed_auths will be called to report to the client what options it has for continuing the authentication.)

The default implementation always returns AUTH_FAILED.

Parameters:

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

  • password (str) – the password given by the client.

  • username

  • password

Returns:

AUTH_FAILED if the authentication fails; AUTH_SUCCESSFUL if it succeeds; AUTH_PARTIALLY_SUCCESSFUL if the password auth is successful, but authentication must continue.

Return type:

int

check_auth_publickey(username, key)

Determine if a given key supplied by the client is acceptable for use in authentication. You should override this method in server mode to check the username and key and decide if you would accept a signature made using this key.

Return AUTH_FAILED if the key is not accepted, AUTH_SUCCESSFUL if the key is accepted and completes the authentication, or AUTH_PARTIALLY_SUCCESSFUL if your authentication is stateful, and this password is accepted for authentication, but more authentication is required. (In this latter case, get_allowed_auths will be called to report to the client what options it has for continuing the authentication.)

Note that you don’t have to actually verify any key signtature here. If you’re willing to accept the key, Paramiko will do the work of verifying the client’s signature.

The default implementation always returns AUTH_FAILED.

Parameters:

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

  • key (PKey) – the key object provided by the client

  • username

  • key

Returns:

AUTH_FAILED if the client can’t authenticate with this key; AUTH_SUCCESSFUL if it can; AUTH_PARTIALLY_SUCCESSFUL if it can authenticate with this key but must continue with authentication

Return type:

int

check_channel_exec_request(channel, command)

Determine if a shell command will be executed for the client. If this method returns True, the channel should be connected to the stdin, stdout, and stderr of the shell command.

The default implementation always returns False.

Parameters:

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

  • command (str) – the command to execute.

Return type:

bool

Returns:

True if this channel is now hooked up to the stdin, stdout, and stderr of the executing command; False if the command will not be executed.

Added in version 1.1.

Parameters:

  • channel (Channel)

  • command (bytes)

check_channel_forward_agent_request(channel)

Determine if the client will be provided with an forward agent session. If this method returns True, the server will allow SSH Agent forwarding.

The default implementation always returns False.

Parameters:

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

Return type:

bool

Returns:

True if the AgentForward was loaded; False if not

If True is returned, the server should create an AgentServerProxy to access the agent.

Parameters:

channel (Channel)

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.

get_allowed_auths(username)

Return a list of authentication methods supported by the server. This list is sent to clients attempting to authenticate, to inform them of authentication methods that might be successful.

The “list” is actually a string of comma-separated names of types of authentication. Possible values are "password", "publickey", and "none".

The default implementation always returns "password".

Parameters:

  • username (str) – the username requesting authentication.

  • username

Return type:

str

Returns:

a comma-separated str of authentication types

class sshmitm.mockserver.MultiUserMockServer(users)

Bases: ServerInterface

Mock server that maps different usernames to different auth methods.

Each entry in users configures what a specific username may use to authenticate. Build entries with the class-level factory helpers:

server = MultiUserMockServer({
    "none":  MultiUserMockServer.none_user(),
    "pw":    MultiUserMockServer.password_user("s3cr3t"),
    "key":   MultiUserMockServer.pubkey_user([my_key]),
    "kbd":   MultiUserMockServer.kbdint_user(
                 prompts=[("OTP: ", True), ("Password: ", False)],
                 answers=["123456", "secret"],
             ),
    "iter":  MultiUserMockServer.kbdint_iterative_user([
                 KbdintRound(prompts=[("OTP: ", True)],    answers=["123456"]),
                 KbdintRound(prompts=[("Password: ", False)], answers=["secret"]),
             ]),
})
Parameters:

users (dict[str, _UserConfig])

check_auth_interactive(username, submethods)

Begin an interactive authentication challenge, if supported. You should override this method in server mode if you want to support the "keyboard-interactive" auth type, which requires you to send a series of questions for the client to answer.

Return AUTH_FAILED if this auth method isn’t supported. Otherwise, you should return an .InteractiveQuery object containing the prompts and instructions for the user. The response will be sent via a call to check_auth_interactive_response.

The default implementation always returns AUTH_FAILED.

Parameters:

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

  • submethods (bytes | str) – a comma-separated list of methods preferred by the client (usually empty)

  • username

  • submethods

Returns:

AUTH_FAILED if this auth method isn’t supported; otherwise an object containing queries for the user

Return type:

int or .InteractiveQuery

check_auth_interactive_response(responses)

Continue or finish an interactive authentication challenge, if supported. You should override this method in server mode if you want to support the "keyboard-interactive" auth type.

Return AUTH_FAILED if the responses are not accepted, AUTH_SUCCESSFUL if the responses are accepted and complete the authentication, or AUTH_PARTIALLY_SUCCESSFUL if your authentication is stateful, and this set of responses is accepted for authentication, but more authentication is required. (In this latter case, get_allowed_auths will be called to report to the client what options it has for continuing the authentication.)

If you wish to continue interactive authentication with more questions, you may return an .InteractiveQuery object, which should cause the client to respond with more answers, calling this method again. This cycle can continue indefinitely.

The default implementation always returns AUTH_FAILED.

Parameters:

responses (list[str]) – list of str responses from the client

Returns:

AUTH_FAILED if the authentication fails; AUTH_SUCCESSFUL if it succeeds; AUTH_PARTIALLY_SUCCESSFUL if the interactive auth is successful, but authentication must continue; otherwise an object containing queries for the user

Return type:

int or .InteractiveQuery

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_auth_password(username, password)

Determine if a given username and password supplied by the client is acceptable for use in authentication.

Return AUTH_FAILED if the password is not accepted, AUTH_SUCCESSFUL if the password is accepted and completes the authentication, or AUTH_PARTIALLY_SUCCESSFUL if your authentication is stateful, and this key is accepted for authentication, but more authentication is required. (In this latter case, get_allowed_auths will be called to report to the client what options it has for continuing the authentication.)

The default implementation always returns AUTH_FAILED.

Parameters:

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

  • password (str) – the password given by the client.

  • username

  • password

Returns:

AUTH_FAILED if the authentication fails; AUTH_SUCCESSFUL if it succeeds; AUTH_PARTIALLY_SUCCESSFUL if the password auth is successful, but authentication must continue.

Return type:

int

check_auth_publickey(username, key)

Determine if a given key supplied by the client is acceptable for use in authentication. You should override this method in server mode to check the username and key and decide if you would accept a signature made using this key.

Return AUTH_FAILED if the key is not accepted, AUTH_SUCCESSFUL if the key is accepted and completes the authentication, or AUTH_PARTIALLY_SUCCESSFUL if your authentication is stateful, and this password is accepted for authentication, but more authentication is required. (In this latter case, get_allowed_auths will be called to report to the client what options it has for continuing the authentication.)

Note that you don’t have to actually verify any key signtature here. If you’re willing to accept the key, Paramiko will do the work of verifying the client’s signature.

The default implementation always returns AUTH_FAILED.

Parameters:

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

  • key (PKey) – the key object provided by the client

  • username

  • key

Returns:

AUTH_FAILED if the client can’t authenticate with this key; AUTH_SUCCESSFUL if it can; AUTH_PARTIALLY_SUCCESSFUL if it can authenticate with this key but must continue with authentication

Return type:

int

check_channel_exec_request(channel, command)

Determine if a shell command will be executed for the client. If this method returns True, the channel should be connected to the stdin, stdout, and stderr of the shell command.

The default implementation always returns False.

Parameters:

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

  • command (str) – the command to execute.

Return type:

bool

Returns:

True if this channel is now hooked up to the stdin, stdout, and stderr of the executing command; False if the command will not be executed.

Added in version 1.1.

Parameters:

  • channel (Channel)

  • command (bytes)

check_channel_forward_agent_request(channel)

Determine if the client will be provided with an forward agent session. If this method returns True, the server will allow SSH Agent forwarding.

The default implementation always returns False.

Parameters:

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

Return type:

bool

Returns:

True if the AgentForward was loaded; False if not

If True is returned, the server should create an AgentServerProxy to access the agent.

Parameters:

channel (Channel)

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.

get_allowed_auths(username)

Return a list of authentication methods supported by the server. This list is sent to clients attempting to authenticate, to inform them of authentication methods that might be successful.

The “list” is actually a string of comma-separated names of types of authentication. Possible values are "password", "publickey", and "none".

The default implementation always returns "password".

Parameters:

  • username (str) – the username requesting authentication.

  • username

Return type:

str

Returns:

a comma-separated str of authentication types

static kbdint_iterative_user(rounds)

Multi-round keyboard-interactive: one round per SSH_MSG_USERAUTH_INFO_REQUEST.

Parameters:

rounds (list[KbdintRound])

Return type:

_UserConfig

static kbdint_user(prompts, answers, *, name='', instructions='')

Single-round keyboard-interactive: all prompts sent at once.

Parameters:

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

  • answers (list[str])

  • name (str, default: '')

  • instructions (str, default: '')

Return type:

_UserConfig

static none_user()
Return type:

_UserConfig

static password_user(password)
Parameters:

password (str)

Return type:

_UserConfig

static pubkey_user(pubkeys)
Parameters:

pubkeys (list[PKey])

Return type:

_UserConfig

class sshmitm.mockserver.NoneAuthServer(username='testuser')

Bases: ServerInterface

Accepts none authentication for a single username.

Parameters:

username (str, default: 'testuser')

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_exec_request(channel, command)

Determine if a shell command will be executed for the client. If this method returns True, the channel should be connected to the stdin, stdout, and stderr of the shell command.

The default implementation always returns False.

Parameters:

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

  • command (str) – the command to execute.

Return type:

bool

Returns:

True if this channel is now hooked up to the stdin, stdout, and stderr of the executing command; False if the command will not be executed.

Added in version 1.1.

Parameters:

  • channel (Channel)

  • command (bytes)

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)

get_allowed_auths(username)

Return a list of authentication methods supported by the server. This list is sent to clients attempting to authenticate, to inform them of authentication methods that might be successful.

The “list” is actually a string of comma-separated names of types of authentication. Possible values are "password", "publickey", and "none".

The default implementation always returns "password".

Parameters:

  • username (str) – the username requesting authentication.

  • username

Return type:

str

Returns:

a comma-separated str of authentication types

class sshmitm.mockserver.PasswordServer(password, username='testuser')

Bases: ServerInterface

Accepts password authentication.

Parameters:

  • password (str)

  • username (str, default: 'testuser')

check_auth_password(username, password)

Determine if a given username and password supplied by the client is acceptable for use in authentication.

Return AUTH_FAILED if the password is not accepted, AUTH_SUCCESSFUL if the password is accepted and completes the authentication, or AUTH_PARTIALLY_SUCCESSFUL if your authentication is stateful, and this key is accepted for authentication, but more authentication is required. (In this latter case, get_allowed_auths will be called to report to the client what options it has for continuing the authentication.)

The default implementation always returns AUTH_FAILED.

Parameters:

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

  • password (str) – the password given by the client.

  • username

  • password

Returns:

AUTH_FAILED if the authentication fails; AUTH_SUCCESSFUL if it succeeds; AUTH_PARTIALLY_SUCCESSFUL if the password auth is successful, but authentication must continue.

Return type:

int

check_channel_exec_request(channel, command)

Determine if a shell command will be executed for the client. If this method returns True, the channel should be connected to the stdin, stdout, and stderr of the shell command.

The default implementation always returns False.

Parameters:

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

  • command (str) – the command to execute.

Return type:

bool

Returns:

True if this channel is now hooked up to the stdin, stdout, and stderr of the executing command; False if the command will not be executed.

Added in version 1.1.

Parameters:

  • channel (Channel)

  • command (bytes)

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)

get_allowed_auths(username)

Return a list of authentication methods supported by the server. This list is sent to clients attempting to authenticate, to inform them of authentication methods that might be successful.

The “list” is actually a string of comma-separated names of types of authentication. Possible values are "password", "publickey", and "none".

The default implementation always returns "password".

Parameters:

  • username (str) – the username requesting authentication.

  • username

Return type:

str

Returns:

a comma-separated str of authentication types

class sshmitm.mockserver.PublicKeyServer(accepted_key)

Bases: ServerInterface

Accepts one specific public key.

Parameters:

accepted_key (PKey)

check_auth_publickey(username, key)

Determine if a given key supplied by the client is acceptable for use in authentication. You should override this method in server mode to check the username and key and decide if you would accept a signature made using this key.

Return AUTH_FAILED if the key is not accepted, AUTH_SUCCESSFUL if the key is accepted and completes the authentication, or AUTH_PARTIALLY_SUCCESSFUL if your authentication is stateful, and this password is accepted for authentication, but more authentication is required. (In this latter case, get_allowed_auths will be called to report to the client what options it has for continuing the authentication.)

Note that you don’t have to actually verify any key signtature here. If you’re willing to accept the key, Paramiko will do the work of verifying the client’s signature.

The default implementation always returns AUTH_FAILED.

Parameters:

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

  • key (PKey) – the key object provided by the client

  • username

  • key

Returns:

AUTH_FAILED if the client can’t authenticate with this key; AUTH_SUCCESSFUL if it can; AUTH_PARTIALLY_SUCCESSFUL if it can authenticate with this key but must continue with authentication

Return type:

int

check_channel_exec_request(channel, command)

Determine if a shell command will be executed for the client. If this method returns True, the channel should be connected to the stdin, stdout, and stderr of the shell command.

The default implementation always returns False.

Parameters:

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

  • command (str) – the command to execute.

Return type:

bool

Returns:

True if this channel is now hooked up to the stdin, stdout, and stderr of the executing command; False if the command will not be executed.

Added in version 1.1.

Parameters:

  • channel (Channel)

  • command (bytes)

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)

get_allowed_auths(username)

Return a list of authentication methods supported by the server. This list is sent to clients attempting to authenticate, to inform them of authentication methods that might be successful.

The “list” is actually a string of comma-separated names of types of authentication. Possible values are "password", "publickey", and "none".

The default implementation always returns "password".

Parameters:

  • username (str) – the username requesting authentication.

  • username

Return type:

str

Returns:

a comma-separated str of authentication types

class sshmitm.mockserver.RecordingServer(password='testpass')

Bases: ServerInterface

Password-auth server that records PTY modes and received signals.

After connecting a client, inspect pty_modes and signals to verify that the SSH-MITM proxy (or any other layer) forwarded them correctly.

Parameters:

password (str, default: 'testpass')

check_auth_password(username, password)

Determine if a given username and password supplied by the client is acceptable for use in authentication.

Return AUTH_FAILED if the password is not accepted, AUTH_SUCCESSFUL if the password is accepted and completes the authentication, or AUTH_PARTIALLY_SUCCESSFUL if your authentication is stateful, and this key is accepted for authentication, but more authentication is required. (In this latter case, get_allowed_auths will be called to report to the client what options it has for continuing the authentication.)

The default implementation always returns AUTH_FAILED.

Parameters:

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

  • password (str) – the password given by the client.

  • username

  • password

Returns:

AUTH_FAILED if the authentication fails; AUTH_SUCCESSFUL if it succeeds; AUTH_PARTIALLY_SUCCESSFUL if the password auth is successful, but authentication must continue.

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.

check_channel_signal_request(channel, signame)
Parameters:

  • channel (Channel)

  • signame (str)

Return type:

bool

get_allowed_auths(username)

Return a list of authentication methods supported by the server. This list is sent to clients attempting to authenticate, to inform them of authentication methods that might be successful.

The “list” is actually a string of comma-separated names of types of authentication. Possible values are "password", "publickey", and "none".

The default implementation always returns "password".

Parameters:

  • username (str) – the username requesting authentication.

  • username

Return type:

str

Returns:

a comma-separated str of authentication types

pty_modes: bytes | None
signals: list[str]
sshmitm.mockserver.start_server_thread(interface_factory, host_key=None, bind='127.0.0.1', port=0, connection_timeout=30.0, sftp_files=None)

Start an SSH server in a background thread.

Parameters:

  • interface_factory (Callable[[], ServerInterface]) – called once per connection to produce a ServerInterface

  • host_key (PKey | None, default: None) – server host key; a temporary RSA-2048 key is generated if None

  • bind (str, default: '127.0.0.1') – address to listen on

  • port (int, default: 0) – port to listen on; 0 picks a free port

  • connection_timeout (float, default: 30.0) – per-connection transport join timeout in seconds

  • sftp_files (dict[str, bytes] | None, default: None) – optional in-memory filesystem {path: content} exposed via the SFTP subsystem. When None, SFTP is not supported.

Return type:

tuple[int, Event, Event]

Returns:

(actual_port, stop_event, closed_event) Call stop_event.set() to request shutdown. closed_event is set once the listening socket is fully closed.

On this page
Edit on GitHub