{"id":21539700,"url":"https://github.com/ramonmeza/pythonsshservertutorial","last_synced_at":"2025-04-10T03:26:16.825Z","repository":{"id":65417732,"uuid":"284814944","full_name":"ramonmeza/PythonSSHServerTutorial","owner":"ramonmeza","description":"A tutorial on creating an SSH server using Python 3, as well as the Paramiko library. It also will cover how to Dockerize this app.","archived":false,"fork":false,"pushed_at":"2025-03-07T12:37:45.000Z","size":32,"stargazers_count":47,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-24T04:43:37.972Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ramonmeza.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-03T21:53:42.000Z","updated_at":"2025-03-07T09:49:23.000Z","dependencies_parsed_at":"2025-02-12T20:21:31.953Z","dependency_job_id":"0aa883b1-c008-4aad-92fa-0cdaaf83ef20","html_url":"https://github.com/ramonmeza/PythonSSHServerTutorial","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramonmeza%2FPythonSSHServerTutorial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramonmeza%2FPythonSSHServerTutorial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramonmeza%2FPythonSSHServerTutorial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramonmeza%2FPythonSSHServerTutorial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ramonmeza","download_url":"https://codeload.github.com/ramonmeza/PythonSSHServerTutorial/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248150008,"owners_count":21055845,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-24T04:16:10.971Z","updated_at":"2025-04-10T03:26:16.817Z","avatar_url":"https://github.com/ramonmeza.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PythonSSHServerTutorial\n\nA tutorial on creating an SSH server using Python 3 and the `paramiko` package. It will also cover how to \"dockerize\" the application using Docker to allow it to be run on other platforms.\n\n## Prerequisites\n\nApplications:\n\n- Python 3.8+\n- venv\n- Docker\n- OpenSSH (client and server)\n\n`pip` packages:\n\n- paramiko\n\n## Creating the Application\n\n### Create a `venv`\n\nA virtual environment allows you to separate dependencies used in your app from those globally installed on your local machine. It's probably a good idea to use a `venv` if you plan to redistribute your code.\n\n```sh\npython -m venv .env\n```\n\nYou can activate your environment using the following command:\n\n```sh\n./.env/Scripts/activate\n```\n\nOnce activated, any `python` or `pip` commands you make will be executed using `python` and `pip` executable within your `venv`.\n\nInstall the following:\n\n```sh\npip install paramiko\n```\n\n### Creating the Shell\n\nOur shell will extend the `cmd` module's `Cmd` class. The `Cmd` class provides us a way to create our own custom shell. It provides a `cmdloop()` function that will wait for input and display output. This class also makes it trivial to add custom commands to our shell.\n\nWe start by importing the `cmd` module's `Cmd` class and extending from it in our shell class:\n\n```py\nfrom cmd import Cmd\n\nclass Shell(Cmd):\n```\n\nNext we set some properties of our class. These properties are going to be overriden from the base `Cmd` class:\n\n```py\nintro='Custom SSH Shell'\nuse_rawinput=False\nprompt='My Shell\u003e '\n```\n\n| Property       | Description                                                                                                                                                          |\n| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `intro`        | A one time message to be output when the `cmdloop()` function is called.                                                                                             |\n| `use_rawinput` | Instead of using `input()`, this will use `stdout.write()` and `stdin.readline()`, which means we can use any `TextIO` instead of just `sys.stdin` and `sys.stdout`. |\n| `prompt`       | allows us to use a custom string to be displayed at the beginning of each line. This will not be included in any input that we get.                                  |\n\nNow we can create our `__init__()` function, which will take two I/O stream objects, one for `stdin` and one for `stdout`, and call the base `Cmd` constructor.\n\n```py\ndef __init__(self, stdin=None, stdout=None):\n    super(Shell, self).__init__(completekey='tab', stdin=stdin, stdout=stdout)\n```\n\nWe can now create a custom `print()` function, which will utilize the `Cmd` class's `stdout` property, instead of using the default `print()` which uses `sys.stdout`. If we use `print()`, any output will go to our server's local screen and not the client when we hook up SSH later on.\n\n```py\ndef print(self, value):\n    # make sure stdout is set and not closed\n    if self.stdout and not self.stdout.closed:\n        self.stdout.write(value)\n        self.stdout.flush()\n\ndef printline(self, value):\n    self.print(value + '\\r\\n')\n```\n\nNow we can create our command functions. These are functions that will execute when the corresponding command is executed in the shell. These functions must be formatted in the following way: `do_{COMMAND}(self, arg)`, where we replace `{COMMAND}` with the string that will need to be entered in the shell to execute the command. For our purposes, we will create `do_greet()` and `do_bye()`. One important note is that even if we don't use the `arg` parameter, like we don't in `do_bye()`, it still needs to be included.\n\n```py\ndef do_greet(self, arg):\n    if arg:\n        self.printline('Hey {0}! Nice to see you!'.format(arg))\n    else:\n        self.printline('Hello there!')\n\ndef do_bye(self, arg):\n    self.printline('See you later!')\n    return True\n```\n\nOne final thing we can do, just to make things look a little nicer to the client, is override the `emptyline()` function, which will execute when the client enters an empty command.\n\n```py\ndef emptyline(self):\n    self.print('\\r\\n')\n```\n\nNow we can test our shell to make sure everything works. The following code is just a test and is not included in the repository.\n\n```py\nfrom Shell import Shell\n\nif __name__ == '__main__':\n    my_shell = Shell()\n    my_shell.cmdloop()\n```\n\nWhen we run the code we should get something like this as output.\n\n```\nCustom SSH Shell\nMy Shell\u003e greet\nHello there!\nMy Shell\u003e greet ramon\nHey ramon! Nice to see you!\nMy Shell\u003e bye ramon\nSee you later!\n```\n\n### Creating the Server Base Class\n\nWe can now move on to creating the server base class, which will contain functionality for opening a socket, listening on a separate thread, and accepting a connection, where then it will call an abstract method to complete the connection and setup the shell for the connected client. The reason we do this as a base class, and not as a single server class is so we can support different connection types, such as Telnet.\n\nFirst we need to import some modules and extend the ABC class in our own `ServerBase` class.\n\n```py\nfrom abc import ABC, abstractmethod\nfrom sys import platform\nimport socket\nimport threading\n\nclass ServerBase(ABC):\n```\n\nNext, let's create the `__init__()` function and initialize some properties for later use:\n\n```py\ndef __init__(self):\n    self._is_running = threading.Event()\n    self._socket = None\n    self.client_shell = None\n    self._listen_thread = None\n```\n\n| Property         | Description                                                                                                                                                           |\n| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `_is_running`    | a multithreaded event, which is basically a thread-safe boolean                                                                                                       |\n| `_socket`        | this socket will be used to listen to incoming connections                                                                                                            |\n| `client_shell`   | this will contain the shell for the connected client. We don't yet initialize it, since we need to get the `stdin` and `stdout` objects after the connection is made. |\n| `_listen_thread` | this will contain the thread that will listen for incoming connections and data.                                                                                      |\n\nNext we create the `start()` and `stop()` functions. These are relatively simple, but here's a quick explanation of both. `start()` will create the socket and setup the socket options. It's important to note that the socket option `SO_REUSEPORT` is not available on Windows platforms, so we wrap it with a platform check. `start()` also creates the listen thread and starts it, which will run the `listen()` function that we will tackle next. `stop()` is even easier, as it simply joins the listen thread and closes the socket.\n\n```py\ndef start(self, address='127.0.0.1', port=22, timeout=1):\n    if not self._is_running.is_set():\n        self._is_running.set()\n\n        self._socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n        self._socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, True)\n\n        if platform == \"linux\" or platform == \"linux2\":\n            self._socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, True)\n\n        self._socket.settimeout(timeout)\n        self._socket.bind((address, port))\n\n        self._listen_thread = threading.Thread(target=self._listen)\n        self._listen_thread.start()\n\ndef stop(self):\n    if self._is_running.is_set():\n        self._is_running.clear()\n        self._listen_thread.join()\n        self._socket.close()\n```\n\nThe `listen()` function will constantly run if the server is running. We wait for a connection, if a connection is made, we will call our abstract `connection_function()` function, which will be implemented inside of our specific server class, described later on. Note that we wrap the code in this function in a `try, except` statement. This is because we expect `self._socket.accept()` to break if the server is stopped.\n\n```py\ndef _listen(self):\n    while self._is_running.is_set():\n        try:\n            self._socket.listen()\n            client, addr = self._socket.accept()\n            self.connection_function(client)\n        except socket.timeout:\n            pass\n```\n\nLastly, we create our abstract `connection_function()` function. This will let us create derived classes of `ServerBase` that specify their own way of dealing with the connection that is being made. For example, later on in our SSH server class, we will connect the SSH `Transport` objects to the connected client socket within `connection_function()`. But for now, this is all it is:\n\n```py\n@abstractmethod\n    def connection_function(self, client):\n        pass\n```\n\n### Creating the ServerInterface\n\n[`ServerInterface` Documentation](http://docs.paramiko.org/en/stable/api/server.html)\n[demo_server.py from paramiko repository](https://github.com/paramiko/paramiko/blob/master/demos/demo_server.py)\n\nThis is probably the worst part of this entire project. Making sense of the information available on creating an SSH server is both daunting and exhausting, but I was able to kind of piece it together, at least to the point where it works. Preface aside, we are going to be implementing `ServerInterface` from the `paramiko` package. This interface allows us to set up the SSH authentication and gives us access to connecting clients' `stdin` and `stdout` streams. This is essential to getting our SSH shell working, since `paramiko` takes care of the low level SSH stuff, like `Transport` objects. Let's get on with it.\n\nFirst let's import `paramiko` and create our class which inherits from `ServerInterface`.\n\n```py\nimport paramiko\n\nclass SshServerInterface(paramiko.ServerInterface):\n```\n\nNow we can override the methods that we need in order to get authentication to work. These are methods you can read about in the `paramiko` documentation link provide at the top of this section. If you omit these methods you won't be able to get your SSH client to connect to the server, since by default some of these methods will return values which block the connection.\n\n```py\ndef check_channel_request(self, kind, chanid):\n    if kind == \"session\":\n        return paramiko.OPEN_SUCCEEDED\n    return paramiko.OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED\n\ndef check_channel_pty_request(self, channel, term, width, height, pixelwidth, pixelheight, modes):\n    return True\n\ndef check_channel_shell_request(self, channel):\n    return True\n```\n\nI'll go over a little of what I know about these methods. First, we have to understand what a channel is. Channels provide a secure communication route between the client and the host over an unsecure network. Since we are creating an SSH server, we need to be able to create these channels to allow clients to connect to us. For this, we will need to override `check_channel_request()` to return `OPEN_SUCCEEDED` when the `kind` of channel requested is a `session`. Next we need to override `check_channel_pty_request()` to return `True`. This allows our client to interact with our shell. Finally we can override `check_channel_shell_request()` to return `True`, which allows us to provide the channel with a shell we can connect to it (done in the next section).\n\nWith all of that out of the way, let's override the method that will allow us to use username and password authentication. If you want to use public SSH keys or gssapi authentication instead, you will need to override the corresponding methods found in the `paramiko` documentation link. You should also look at the `demo_server.py` link I provided at the top of this section, which proved to be a valuable resource while creating this tutorial.\n\n```py\ndef check_auth_password(self, username, password):\n    if (username == \"admin\") and (password == \"password\"):\n        return paramiko.AUTH_SUCCESSFUL\n    return paramiko.AUTH_FAILED\n```\n\nIt's as simple as that. However, storing usernames and passwords in plain text is a bad idea, but since this isn't a tutorial on application security, it will do. I urge you to come up with a better solution if you are using this publicly. You will want to create a database to store your usernames and hashed passwords, where then you will then be able to fetch, unhash and check their authenticity here.\n\nThis next section is optional, but will add a little flair to your SSH server. We will override the `get_banner()` method, which will display a message when a client first connects to our server but is not yet authenticated. This is different than our shell's `intro` property, since that happens when you get to the shell. The banner is displayed before that point, so if you define `get_banner()` here and `intro` in your shell, first your banner will show, after authentication your shell's `intro` will show. Note that `get_banner()` returns a tuple where the first element is banner string and the second element is the language in `rfc3066` style, such as `'en-US'`.\n\n```py\ndef get_banner(self):\n    return ('My SSH Server\\r\\n', 'en-US')\n```\n\nOkay, that wasn't as painful as I thought it would be, so let's get on to the real fun part of this.\n\n### Creating the SSH Server\n\nThe `SshServer` class is where things start to get spicy. That said, the class is actually very simple since we are just implementing the `connection_function()` from the `ServerBase` class we created earlier. Let's start by importing some modules we've created, as well as `paramiko`, and create our server class which will inherit from `ServerBase`.\n\n```py\nimport paramiko\n\nfrom src.server_base import ServerBase\nfrom src.ssh_server_interface import SshServerInterface\nfrom src.shell import Shell\n\nclass SshServer(ServerBase):\n```\n\nNext we need to add a property to our class which will hold the host's private RSA key. We do this in the `__init__()` function and use `paramiko`'s `RSAKey.from_private_key_file()` function.\n\n```py\ndef __init__(self, host_key_file, host_key_file_password=None):\n    super(SshServer, self).__init__()\n    self._host_key = paramiko.RSAKey.from_private_key_file(host_key_file, host_key_file_password)\n```\n\nFinally, we have to override the `connection_function()` function. In here we will first create the `Transport` object and add our host key to it. Then we start our SSH server, which will use the `SshServerInterface` class that we created. Next we create the channel that will be used over the `Transport`. This channel provides stream I/Os that we can hook up to our client shell. We start the shell using the `cmdloop()` function, which blocks execution until we call `bye` from our client. Finally we close the channel.\n\n```py\ndef connection_function(self, client):\n    try:\n        session = paramiko.Transport(client)\n        session.add_server_key(self._host_key)\n\n        server = SshServerInterface()\n        try:\n            session.start_server(server=server)\n        except paramiko.SSHException:\n            return\n\n        channel = session.accept()\n        stdio = channel.makefile('rwU')\n\n        self.client_shell = Shell(stdio, stdio)\n        self.client_shell.cmdloop()\n\n        session.close()\n    except:\n        pass\n```\n\n### Running the SSH Server\n\nFinally we can test all of our code up to this point. First we import our `SshServer` class we just created. Next we simply create our `SshServer`, passing it the location of our private RSA key and the corresponding password and start the server. If you need to create your SSH keys, I suggest either looking at `main.py` in this repository, or looking at either [this article](https://phoenixnap.com/kb/generate-ssh-key-windows-10), which explains how to do it on windows, or [this one](https://www.ssh.com/ssh/keygen/) which explains how to do it on Linux.\n\n```py\nfrom src.ssh_server import SshServer\n\nif __name__ == '__main__':\n    server = SshServer('C:/Users/ramon/.ssh/id_rsa')\n    server.start()\n```\n\nWe now run the code using the command `python3 main.py`. We can open up a new Terminal/PowerShell/CMD window and try to connect to our SSH server using the following command: `ssh admin@127.0.0.1 -p 22`. This command will try to connect to an SSH server running on 127.0.0.1:22 as the username `admin`. If you use a different username, change it here. Once you run this command, you should see the banner text you set in our `SshServerInterface` class earlier, as well as a prompt to enter our password. For this example, we can type in `password` and we are given access to an instance of our custom shell! Exciting!\n\nYou've noticed there are some issues. Yeah, I know. It's not perfect, but hopefully this will get people started for creating their own custom shells and custom SSH servers. If you know how to fix any of the issues, like how the spacing is all out of whack, please create a pull request so we can fix these issues and provide the correct information to everyone.\n\n## Dockerize the App\n\nCool, so our SSH server works. Now we want to use this somewhere else. Docker is the answer. Let's learn how we can dockerize our app and get it running everywhere (that has Docker installed)!\n\n### `requirements.txt`\n\n`requirements.txt` is a file created for us by `pip`. It includes all of the packages that are installed within our environment. If you used `venv` to create your environment, this will result is a small file with just the packages we've used. Run the following command to generate your `requirements.txt` file once you're ready to Dockerize your application:\n\n```sh\npip freeze \u003e requirements.txt\n```\n\n### Application Modifications\n\nWe need to ensure our private key is generated within our Docker container and that we use this file within our container as our private key within our app. This is as simple as changing the path to our private key in `main.py` to `~/.ssh/id_rsa`.\n\n### `Dockerfile`\n\n`Dockerfile` is where you define environment your container will run within. Technically, your `Dockerfile` is used to create an \"image\", which will then be used to create a \"container\" which runs your application. You can think of the container as an instance of the image.\n\nWhen you break down a `Dockerfile`, you typically will see a `FROM` tag at the top, specifying the base image your image will utilize. In our case, we use `ubuntu`. You can also see within the file are `RUN` commands, which do exactly what they say and run a given command within the build stage of your `Dockerfile`. To reiterate, our `Dockerfile` is our method of defining our environment. You can sort of think of this as setting up a new PC and the commands you'd use to install what you need to get your app running. There's a TON of Docker images to base your `Dockerfile` off of, and it can save you a lot of work if you find a base image that does what you need for your specific case.\n\nFor our app, we simply use Ubuntu, install updates, Python and pip, copy our files into our container, install our pip requirements, expose our desired ports and finally run our application.\n\nAn important note to remember about Docker and writing `Dockerfile` is to keep commands which won't change up top. Generally speaking, installations should be higher in your `Dockerfile` and copying/compiling your application files should be toward the bottom. This allows Docker to cache your images so you don't have to constantly wait for Docker to build and install prerequisites every time you change your source code.\n\n### Building and Running the `Dockerfile`\n\nNow that you've defined the `Dockerfile`, you can build a corresponding image we will eventually use for our container. Run the following command:\n\n```sh\ndocker build . --tag python_ssh_server\n```\n\nThe `build` command takes the path to the directory containing your `Dockerfile` and a tag which we use to easily reference our image in our next command:\n\n```sh\ndocker run --rm -e SSH_PORT=2222 -p 2223:2222 --name my_ssh_app_container python_ssh_server:latest\n```\n\nThe `run` command allows use to specify the name of our container and the image we wish to instantiate from. I also include `--rm`, which removes the container once execution is completed. We also need to specify the ports we wish to expose from our container using `-p`. The syntax for `-p` is `-p [local_port]:[container_port]`, where `container_port` is the port your application uses, and `local_port` is the port which will be mapped to the container. When `local_port` is set to 2223, we connect to our SSH server using `ssh 0.0.0.0 -p 2223` from our local machine.\n\nRead more about these flags in the Docker documentation if you wish.\n\n### Connecting to your Containerized SSH Server\n\nNow that the Docker container is running, you simply SSH in like you would any other SSH server:\n\n```sh\nssh admin@0.0.0.0 -p 2223\n```\n\nHere the server address is `0.0.0.0` (default for Docker containers). We also specify our port using `-p`, where the port matches what we mapped in the container. Once you run this command, you should be connected to your SSH server, running from within a Docker container!\n\n### Conclusion\n\nWe did it! We created a custom SSH shell using Python, which can run anywhere Docker is installed. If you have questions, please raise an issue and I'll do my best to answer your question to the best of my ability and within a _\"timely\"_ (it may take a long time) manner.\n\nThanks for sticking around and learning with me.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framonmeza%2Fpythonsshservertutorial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framonmeza%2Fpythonsshservertutorial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framonmeza%2Fpythonsshservertutorial/lists"}